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To my grandparents: 


For your unmatched support, encouragement, and love. — 


Foreword 


It is a pleasure to present —with our co-publisher Osborne/McGraw- 
Hill— Turbo C Programmer’s Library for the benefit of the many 
users of Borland’s Turbo C. 

The power, flexibility, and portability of Turbo C have won this 
complete, interactive development environment an enthusiastic 
acceptance by the programming community. We have responded to 
that endorsement with a commitment to support professional pro- 
grammers and developers in every way possible: with a technically 
superior product, outstanding technical and customer support ser- 

- vices, and quality books that help them expand their uses of Turbo C. 


Vil 
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Turbo C Programmer’s Library by veteran author Kris Jamsa is, 
therefore, an integral piece in our Turbo C support program. Here, 
in one indispensable volume, are the examples of good code and the 
techniques programmers and developers need to develop a library of 
hundreds of powerful Turbo C routines. In addition, Jamsa provides 
insight into the development of the run-time library to help users 
take full advantage of the library’s routines. | 

We recommend Turbo C Programmer’s Library as the perfect 
companion for developing programs with Turbo C. 


Philippe Kahn 
President 
Borland International, Inc. 


Preface 


Developing a library of Turbo C routines is one of the best ways to 
enhance the productivity of programmers. If you work with other 
programmers, keeping a library of functions will increase every- 
one’s productivity, for several reasons. First, programmers often 
spend a significant amount of time developing routines that already 
exist in other applications. A library of routines can minimize 
duplication of effort because programmer has access to the routines 
in the library. Second, programming skills are improved through 
exposure to “good” coding techniques. another programmer’s code 
provides an important opportunity for information and learning new 
techniques. In addition, you can standardize code and documenta- 
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tion and minimize errors. If you are programming at home, placing 
your routines into a library will greatly improve the organization of 
your disks. | 

This book provides an extensive library of Turbo C routines. 
Each routine was developed to simplify its integration into your 
application programs. This library meets the needs of both the 
novice and experienced Turbo C programmer. The novice can create 
useful programs in just minutes, and the experienced programmer 
can learn how to increase the flexibility of applications through 
memory mapping and pop-up menus. All programmers will learn 
how to write routines that support the DOS pipe, DOS wildcard 
characters, and the DOS and BIOS system services. 


Turbo C Run-Time Library 


For those of you who are already familiar with the Turbo C run- 
time library, you will be pleased to find many routines presented 
here for the first time. By experimenting with the routines in this 
book, you can add significant power to your Turbo C programs. 
manipulation. In other cases, they are provided to increase your 
appreciation of Borland’s routines and to teach you how to use them 
more effectively. | 

For those of you who are already familiar with the Turbo C run- 
time library, you will be pleased to find many routines presented 
here for the first time. By experimenting with the routines in this 
book, you can add significant power to your Turbo C programs. 


Development Philosophy 


This book was written with two major goals. First, the routines had 
to offer new capabilities to Turbo C programmers at all levels of 
experience. For the novice, this book offers valuable information and 
an opportunity to extend his or her knowledge of Turbo C. To meet 
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the diverse needs of advanced programmers, it offers routines for 
dynamic memory manipulation, pop-up menus, memory-mapped 
I/O, and support for DOS wildcard characters. 

The second (and more important) goal was to illustrate good pro- 
gramming practice. Thus, each routine presented in this text has 
the following attributes: 


« Complete documentation 
« Consistent usage 

e Well-structured code 

e Thorough error detection 


e Restriction of side effects 


As you examine the routines in this text, you should note their 
consistent documentation. Since you must examine hundreds of rou- 
tines, consistent documentation is more important than you may at 
first realize. You will also note that the code is quite structured. 
There are no goto statements, and, when applicable, functions have 
only one entry and exit point. Turbo C prototypes have been used 
extensively throughout the text to help the compiler locate as many 
errors as possible. If you have not yet developed your own program- 
ming standards, use the ones in this text for your foundation. 


Chapter Contents 


This text assumes that you are familiar with, or are in the process of 
learning, Turbo C. It is not intended to be a tutorial on Turbo C. 

Chapter 1 provides you with an overview of the Turbo C run-time 
library, introduces C function prototyping, and discusses the conven- 
tions used throughout the text. 

Chapter 2 is a detailed presentation of string manipulation. Sev- 
eral of the functions normally found in the Turbo C run-time library 
are enhanced to provide additional functionality. 


xii 
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Chapter 3 discusses string manipulation using pointers. Many of 
the routines presented in Chapter 2 are greatly simplified by the use 


of pointers. Because string manipulation is common in Turbo C, this 


chapter is critical to understanding the language. 

Chapter 4 examines recursion. Simply stated, a recursive func- 
tion invokes itself to perform a specific task. 

Chapter 5 shows how to develop Turbo C programs that support 
the DOS pipe and I/O redirection. 

Chapter 6 introduces the DOS system services. All of the com- 
mands that you normally issue from the DOS prompt (such as those 
used for subdirectory manipulation) can be called by your Turbo C 
programs. This chapter teaches you how to get the most from DOS. 

Chapter 7 presents the BIOS system services that perform the 
basic input/output services for your computer. You can gain consid- 
erable flexibility by using the BIOS for I/O processing instead of 
standard Turbo C functions. | 

Chapter 8 introduces the ANSI driver that is available to your 


Turbo C programs once ANSI.SYS is installed during system start- ms 


up. The ANSI driver provides enhanced screen output Paneoee 
along with keyboard redefinition. 

Chapter 9 demonstrates advanced file-manipulation bochnianes 
with Turbo C. You will learn how to support DOS wildcard charac- 


ters as well as multiple command-line parameters. 


Chapter 10 presents array-manipulation routines. It also presents 


~ several techniques including the use of macro procedures, to help 


you keep your routines as generic as possible. 

Chapter 11 demonstrates several sorting and searching algo- 
rithms. You will learn the bubble, selection, Shell, and quick sorts as 
well as use sequential and binary searches. 

Chapter 12 examines advanced I/O routines. You will develop 
routines that prompt for and validate integer, floating, and charac- 
ter string values. 

Chapter 18 looks at dynamic memory manipulation. You will 
learn to program singly linked lists, doubly linked lists, and binary 
trees. 

Chapter 14 presents mapped video in Turbo C. Because many of 


the routines update the video display, the chapter presents two 
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assembly language routines that synchronize video memory refer- 
ences to the horizontal screen refresh. 

Chapter 15 examines menu manipulation. It includes several rou- 
tines that work for essentially any menu, and discusses video pop-up 
menus. | 

Appendix A provides an ASCII chart. Appendix B provides the 
calling sequence and notes for each of the routines in the Turbo C 
run-time library. 


Disk Packages 


There are thousands of lines of code in this book. All the routines are 
presented in their entirety, so you can type them at your computer as 
you need them. To save you time and testing, a disk package contain- 
ing all of the routines in this book is available for $39.95 plus ship- 
ping and handling. 

The Turbo C Help disk package provides you with on-line help 
for Turbo C statements, reserved words, and constructs, as well as 
the complete calling sequence and notes on each Turbo C run-time 
library routine. This package allows you to put your Turbo C docu- 
mentation back on the shelf. Turbo C Help is available for $29.95 
plus shipping and handling. 

To order these packages, use the coupons on the following page. 


Please send me the disk package for Turbo C Programmer’s Library. 
My payment of $42.45 (39.95 plus $2.50 shipping and handling) is 
enclosed. (For orders to Canada and Europe, please include $7.50 for 
shipping and handling ($47.45). | 


check 
money order 
Name 
Address 7 
City State ZIP 


Kris Jamsa Software, Inc. Box 26031 Las Vegas, Nevada 89126 


This is solely the offering of Kris Jamsa Software, Inc. Osborne/ McGraw-Hill takes no 
responsibility for the fulfillment of this order. 


Please send me Turbo Help on disk. My payment for $32.45 ($29.95 
plus $2.50 shipping and handling) is enclosed. For orders to Canada 
and Europe, please include $5.00 for shipping and handling 
($34.95). 


check 
money order 
~ Name 
Address 
City State ZIP 


Kris Jamsa Software, Inc. Box 26031 Las Vegas, Nevada 89126 


This is solely the offering of Kris Jamsa Software, Inc. Osborne/McGraw-Hill takes no 
responsibility for the fulfillment of this order. 


Getting Started with 
the Turbo C Library 


This book was written to save you time—development time, coding 
time, and testing time—as you write your Turbo C programs. This 
book provides you with a library (or, specifically, a collection of rou- 
tines) that you can use to complete your Turbo C programs. Because 
the routines in this text are already written, you can simply insert 
them into your Turbo C programs, and, because each routine has 
been thoroughly tested, you can greatly reduce the testing time 
normally associated with program development. If you are new to 
Turbo C, DOS, or the IBM PC, these routines can teach you a great 
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deal about these topics. By examining the source code presented 
here, your Turbo C programs should improve. Considerable time 
and effort has been spent to maintain the readability, modifiability, 
and generic characteristics of each routine. 

As you progress through each chapter, keep in mind that these 
routines are only the start of your Turbo C library. Build on these 
routines and you will find that your library of Turbo C functions 
never seems to stop growing. Feel free to modify any of these rou- 
tines to meet your individual needs. Only by experimenting with 
each function can you fully understand its processing. Libraries 
exist to make your programs easier to develop. poe ane in 
Turbo C should be easy and fun. 


Turbo C Run-Time Labrary 


A major function of any programming library is to reduce the 
duplication of code. After all, if someone else has written code to 
perform a specific task, why reinvent the wheel? Borland Interna- 
tional, Inc., provides you with a powerful collection of routines called 
the run-time library that you should use whenever possible. Borland 
developed Turbo C and employs many of the true Turbo C experts. 
All of the routines in the run-time library are well written and 
highly optimized. You should spend considerable time becoming 
familiar with these routines. Each of these routines is listed in 
Appendix B. The time you spend now becoming conversant with the 

run-time library routines will save you much more time in the 
future. 

In some cases, you may wonder why vouiines in this text appear 
to duplicate functions in the run-time library. In most cases, the 
answer is simply for instruction. In the case of strings, Turbo C pro- 
vides a powerful collection of string-manipulation routines in the 
run-time libraries. Because strings are so widely used, you should 
fully understand string manipulation. The only way to accomplish 
this is by examining source code. Without source code for these rou- 
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tines, you could never modify them to meet your individual needs. 
By examining the routines in this text, you will gain a much better 
understanding of the Turbo C run-time library. 

If you are performing serious Turbo C development, you should 
strongly consider purchasing the run-time library source code from 
Borland. This source code provides excellent examples of how to get 
the most from Turbo C. 


Routine Presentation 


All of the routines in this text are presented in the same fashion: 
first pictorially and then in source code. For example, consider the 
routine sum that receives two values and returns their sum. This 
routine is presented pictorially as follows: 


int a = 300; 
int b = 625; 


Sum of the 
two parameters 


First, note the two variables passed to the routine: 


int a = 300; 


int b = 625; 
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This illustration tells you that both of the variables are of type int 
and gives you possible values that can be assigned to each. In this 
case, the values 300 and 625 will be added. 

Next, note how the returned value is presented: 


Sum of the 
two parameters 


Each routine that returns a value will show the return value coming 
out of the bottom of the box. Consider the routine add__and— 
display. Rather than returning the result of the addition, this rou- 
tine instead aiplaye it to the screen, as shown here: 


int a = 300; | 
d__and__display , 


_ Any routine that writes data to the screen will be presented in this 
manner. 
Similarly, if the routine get_a_character uses the keyboard, it 
is presented as follows: 
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get_.a__character 


Character entered by the user 


If a routine modifies one or more of its parameters, the updated 
parameter is shown exiting the right-hand side of the box, as follows: 


char str[80]; get__a_-string “string entered” 


The goal of presenting each routine pictorially, is to build in your 
mind an image of the processing of the routine before you examine 
the source code. In many cases, you will find that you really do not 
need to know how a routine works, but rather what the routine does. 
These illustrations are meant to aid you in understanding the pro- 
cessing involved. | 

The source code for each routine is also presented in a consistent 
manner. Given the routine sum presented previously, the code will 
contain the following: 


Sum (a, b) 


Return the sum of the two integer values specified. 


+ + € * HF 


a (in): First value to sum. 
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* b (in): Second value to sum. 
* : 
* result = sum (6, 7); 
* 
* / 
sum (a, b) 
Ine ay.\bs 
{ 


return (a + b); 


Note the descriptive header that precedes the function code: 


™ 


+ + + + F FF HF HF HF 


sum (a, b) 
Return the sum of the two integer values specified. 


a (ans? FiPse value to sum. 
b (in): Second value to sum. 


result = sum (6,7)? 


4 


By examining this header information, you should be able to under- 
stand the routine’s function, variables, and usage before you exam- 
ine the source code that follows. Note that each parameter in the 
descriptive block is labeled as either (in) or (out). A parameter that 
does not change within a function is an (in) parameter. A function 
that does not use the original parameter value (but rather changes 
it) is an (out). If the function uses and then modifies the parameter, 
it is labeled (in/out). 7 


Understanding Function 
Prototypes 


For those who have never worked with Turbo C prototypes, you are 
in for a real treat. Turbo C allows you to define and declare a func- 
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tion. When you define a function, you provide its source code, as 
shown here: 


float sum (a, b, c) 
float a, b, c; 


le 


return (a + b +c); 


When you declare a function, you tell another function information 
about the first function. 


float sum (); 


For years, many C programmers declared C functions only when 
the functions returned a value of a type other than int. By proto- 
typing your functions, you can prevent many run-time errors simply 
because the errors are caught by the compiler. 

Consider the following example: 


float sum: ‘Ca; By. ec) 
float a, b, c; 
{ 
return (a + b +c); 


} 


main () 
{ 


float sum (); 


print’ ("Sst \n" sum (i. 2;,. 254) )9 
} 


In this case, the routine sum expects three parameters, but only two 
are present. Because the compiler has no knowledge about sum, the 
program code is acceptable. Hence, a possibly difficult-to-detect run- 
time error will occur. 

By using prototypes you can prevent this error from occurring. 
Notice how you can change the function header for sum. You move 
the location of the parameter definitions within the parentheses, as 
shown here: | 
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float sum (float a, float b, float c) 
{ 


return (a + b +c); 


Within main, you must declare sum as a function and specify the 
type of each parameter, as shown here: 


float sum (float a, float b, float c) 
{ 


return (a + b +c); 


Main () 
{ 
float sum (float, float, float); 


Deine’ C"Si\n" sum (ls2) 224) )5 
} 


Because main has knowledge about sum, it detects the invocation — 


printf (<"Se\n",. sum (1.2; 2.4)) 7 


as an error during compilation time. 

During the development of this text, function prototyping saved 
me an immeasurable amount of time. You should always declare 
each routine you will use, along with the types of each of the rou- 
tine’s arguments. You will save considerable testing and debugging | 
time in the future. 


Assembly Language Routines 


Chapters 14 and 15 present several functions based on two assembly 
language routines that provide a hardware interface. In order to use 
these routines, you must have either the Microsoft macro assembler 
or the object code library disk discussed in the Preface. A goal in — 
any program development is to write as much of the software as 
possible in a high-level language. That goal has been met here. 
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Unfortunately, for the routines to execute fast enough to prevent 
snow on the screen display, the two interface routines must be writ- 
ten in assembly language. 

To compile routines that contain in-line assembly language code, 
you must use the TCC command-line compiler (as opposed to the TC 
integrated environment). 


A Final Word 


Have fun and experiment. You have hundreds of routines with which 
to work. Your program development time should be drastically 
reduced. Make use of this time by studying the source code pre- 
sented in this text. 


String 
Manipulation 


The most widely used routines in any C programmer’s library are 
those that perform string manipulation. Most C compilers provide a 
solid library of general-purpose string-manipulation functions and 
Turbo C is no exception. Because of the tremendous use of strings, 
however, you must fully understand how C stores and manipulates 
strings. 

This chapter examines strings in detail. Many possible imple- 
mentations could be used to solve the problems presented in this 
chapter. By the end of this chapter, you should be able to recognize 
the factors that make one solution “better” than another. This chap- 
ter will help you understand how some of Turbo C’s standard library 
functions work while providing you with a complete set of string- 
manipulation routines. Your programs will exploit each of these rou- 
tines on a regular basis. 
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Getting Started 


A character string is a sequence of one or more characters. The C 
language stores character strings as arrays, in which each character 
in the string resides in contiguous memory locations. For example, 
consider the string declaration shown here: 


char some_string [255]; 


In this case, C creates a character string variable with storage space 
for 255 characters. Like all C arrays, C strings are indexed begin- 
ning at offset 0. As such, the previous declaration creates an array of | 
characters indexed as shown in Figure 2-1. 

By default, C contains no built-in method to ieeeenine the 
number of characters contained in a C string. Instead, the standard 


some_stringio} [—__] 


some_string[1] 
some__string[2] 
some__string[3] 


some__string[251] Peel 
-some__string[252] ee 
some__string[253] aaa 


some__string[254] 


some__string 


Figure 2-1. Indexed array of characters 
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is to place a null character (ASCII 0) immediately following the last 
character in the string. Thus, C stores the string "Turbo C” as char- 
acters in an array with the null character appended (see Figure 
2-2). 

Because each character string terminates with the null charac- 
ter, you can determine the number of characters in the string s 
simply by searching for the null character (\0), as shown here: 


for (i = 0; s[i] != ’\0O"; i++) 


° 
s 


Each time you specify a character string within double quotation 
marks, Turbo C places the null character at the end of the string for 
you. For example: 


#define COMPILER "Turbo C" 


Figure 2-2. Placement of null character in a string 
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In most cases, however, ensuring that a character string is ter- 
minated by a null character becomes the responsibility of the pro- © 
grammer, as shown here: | 


main () 
char alphabet [27]; /* 26 letters and space for null */ 
char letter; 
int index; 


for (index = 0, letter = ’A’; letter <= 'Z’; index++, letter+t) 
alphabet [index] = letter; . 


alphabet [index] = ’\0’; /* append the null character */ 


printf ("%s\n", alphabet) ; 


Strings as Parameters 


One of the contributing factors that helps you write generic string- 
manipulation routines is the manner in which C treats arrays passed 
to functions. Assume that you have a function called string__length 
that returns the number of characters in a string. Invoke it from 
your program, as shown here: 


count = string length (strvar); 


Since you are passing a character array, you can declare the string 
within the function with no array bounds: 


string length (char str[]) 


/* code here */ 
} 


All of the routines in the remainder of this chapter declare the 
formal string parameters in this manner. 
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String Length 


The following routine returns the length of a string by examining 
succeeding characters for the null character: 


* 
. string length (string) 
* Return the number of characters in the string. 
* 
* string (in): string to return the length of. 
* 
* count = string length (string); 
i 


/ 
int string length (char string[]) 
{ 


int 2: 


for (1 = 0} string/li]?; i++) 


’ 


return (i); 


} 


Array Bounds 


In most programming applications, time is always a tradeoff against 
other factors. In some cases, the tradeoff becomes time versus space. 
String-manipulation routines are no exception. 

Consider this routine, which copies the contents of one string to 
another: 


VO1d first copy: (source, Larger) 
Copy the contents of the source string to the target. 


sl (in): source string containing characters to copy. 
s2 (out): string receiving characters copied. 


first copy ("This is a test", stringvar); 


first _copy does not perform bounds checking. 


* + + © + +  * FF OF OF OF 
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void first copy (char s1[], char s2[]) 


{ 

int. 1: 

for (1 = 0; slf{i) != "\0O'; ++i) 
s2[i] = sl[il]; 

s2 (a). = 7 X\0"s 


This routine copies characters from the first string (s1) to the second 

(s2), one at a time, until the null character is found (see Figure 2-3). 
This routine will work properly in most cases. However, con- 

sider this program, which uses first—copy: 

main () 


{ . 
s2(5]; 


first_copy ("long string", s2); 
} 


Here, first—copy appears to copy characters from si to s2, as 
desired. Actually, however, the copy has exceeded the array bounds 
of s2. The character string "long string” contains 11 characters 


Figure 2-3. Copying characters from first string to second string 
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(including the null character), while s2 only has space for 5. As a 
result, first—copy overwrites the contents of the routine’s stack 
space and produces an error. To remedy this problem, you can 
include a parameter that defines the maximum number of charac- 
ters to be assigned to the target string, as shown here: 


second copy ("long string", s, sizeof(s)); 


The following routine implements second—copy: 


es 

* int second copy (source, target, array bound) 

* 

* Copy the source string to the target string variable. 

* 

* sl (in): Contains the characters to be copied. 

* s2 (out): Receives the characters copied. 

* maxchar (in): specifies the maximum number of characters 

x that s2 can store. 

* 

* status = second copy ("This is", stringvar, sizeof (stringvar) ); 
* 

* If the array bounds are exceeded, second copy returns the value 
* 1; otherwise it returns the value 0. 

* 

* 


/ 


int second copy (char sl[{], char s2[], int maxchar) 
{ 
int index; 


maxchar--; /* leave space for null */ 
for (index = 0; (slf{index] != ’\0’) && index < maxchar; index+tt) 
s2[index] = sl [index]; 


s2[index] = ’\0’; 


return (sl[{index] && (index == maxchar)); 
} 


This routine indeed allows you to prevent the error that previously 
occurred. However, because you must now include the second test 


(sl{index] != ’\0’) && (index < maxchar) 


you increase the required processing time for each iteration of the 
loop. 
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Minimizing Source Code 


Although the previous routines were quite readable (assuming that 
you are familiar with C arrays), you can simplify (reduce) the code 
required to implement them. 

Consider this code fragment: | 


for (i = 0; sl[i] != ’\0O"%; ++i) 
s2[i] = sl[il; 


s2[i] = '\0'; 


C allows you to change this code, as shown here: 


for (i = 0; (s2({i] = sl[i]) != ’\0"%; ++1) 


In both cases, each fragment performs the identical function. In 
the second code fragment, Turbo C will test the value that is 
assigned to s2 with each iteration of the loop. If that value is null, C 
terminates the loop. If not, C simply assigns the next character in s1 
to s2, thus repeating the test. Once the null character has been 
assigned to s2, the loop terminates. Since the code contained within 
the for loop has already assigned the null character to s2, you can 
eliminate the line | 


s2[i] = ’\0'; 


When this code assigns the null character to s2, the value 
returned from the test 


(s2[i] = sl[i]) != ’\0’ 


is 0 (null is the ASCII 0). Since C equates the Boolean false to 0, you 
can again modify this code as follows: 


for (i = 0; (s2[i] = sl1[i]) ; ++i) 
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As you develop your C string-manipulation routines, keep the 
following in mind: 


e Is execution speed more important than reliability? 


¢ Is the code as simple as possible? 


e Does the code maintain readability? 


As you develop your library of string-manipulation routines, you 
should constantly attempt to balance the tradeoffs between speed, 
reliability, and readability. Actual implementation will likely be 
based upon your programming requirements. As such, the decision 
of which routine to use can often have as great an impact on your 
program as the code that actually implements the routine. 


String Copy 


Two functions implement a string copy routine. The first, fast—copy, 
copies the contents of the first string specified to the second without 
bounds checking. The second, copy__string, also performs the same 
processing, but with bounds checking enabled. 


char *s="TEST” es “TEST” 
char *s2; Boer, “TEST” 


Warning: fast__copy does not perform bounds checking. 


™~ 
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void fast _copy (source, target) 
Copy the contents of the source string to the target. 


Sl (in): source string containing characters to copy. 
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s2 (out): string receiving characters copied. 
fast_copy ("This is a test", stringvar); 
fast_copy does not perform bounds checking. 
/ 


* 
* 
* 
* 
* 
* 
* 


void fast copy (char s1[], char s2[]) 
{ 
int i; 
for (i = .0; (s2[i] = sl[i]) ; ++i) 


} 


lA 


If the routine cannot successfully complete the copy, it returns 
the value 1. Otherwise, it returns the value 0. 


char *s="TEST” ; ; 
int maxchar=sizeof(s1) TEST 


0 Successful copy 
1 Incomplete copy 


int copy string (source, target, array bound) 
Copy the source string to the target string variable. 
sl (in): contains the characters to be copied. 
s2 (out): receives the characters copied. | 
maxchar (in): specifies the maximum number of characters 
that s2 can store. 
status = copy string ("This is", stringvar, sizeof (stringvar) ); 


If the array bounds are exceeded, string copy returns the value 
1; otherwise it returns the value 0. 


/ 
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int copy string (char sl[], char s2[], int maxchar) 
int i; 
maxchar--; /* leave space for null */ 


for (i = 0; (s2[i] = sl[i]) && i < maxchar; i++) 


‘ 


if (i == maxchar && sl[i}) /s see if characters remain in sl */ 
{ 
s2{i] = '\0’; 
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return (1); 


else 
return (0); 
} 


String Append 


The following two routines append the contents of the first string 
specified to the second. The routine first locates the end of the 
second string (the null character) and then begins appending char- 
acters from the first string at that point. Once the null character 
from the first string is appended to the second string, the loop ter- 
minates. As before, the routine called fast—append does not perform 
bounds checking, but the routine called append—string does. 


char «s="ONE"” fast__append 


char *s1="PART” "PART ONE” 


Warning: fast—append does not perform bounds checking. 


void fast _append (source, target) 
Append the contents of the source string to the target. 


sl (in): source string containing characters to append. 
s2 (out): string receiving characters copied. 


fast_append ("This is a test", stringvar); 
fast _append does not perform bounds checking. 


/ 
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void fast_append (char sil[], char s2[]) 
{ 


int i, 4 


for (i = 0; s2[i] ; ++i) {/* tind the end of <s2 */ 


s 


for (j = 0; s2[i] = sl[j]; itt, j++) /* append sl */ 


v 


} 
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If the following routine cannot successfully append the string, it 
returns the value 1. Otherwise, it returns the value 0. 


int maxchar=sizeof(s2) "PART ONE” 
char *s="ONE" append -_string 
char *s2="PART"” 


O Successful 
1 Incomplete 


insert string (source, target, location, array bounds) 


Insert the contents of the source string to the target 
at the index location specified. 


sl (in): source string containing characters to copy. 
s2 (out): string receiving characters copied. 

index (in): location within target to insert s1 at. 
maxchar (in): maximum number of characters in s2. 


insert string ("Pocket", stringvar, 6, sizeof (stringvar) ); 


insert_string returns one of the following: 
-1 insufficient memory 0 successful insertion 1 incomplete 


+ + + FH * FF FF + HF FF FF 


™ 


ant insert string (char sl{], char s2[], int start index, int maxchar) 
{ 


int i, j, lenl, len2; 


char *temp; 
void *calloc(unsigned, unsigned) ; 


for (lenl = 0; sl[leni]; ++lenl) /* get length of sl */ 


’ 


for (len2 = 0; s2[len2]; ++len2) /* get length of s2 */ 


tf 


if (start_index > len2) start index = len2; /* append */ 


if ((temp = (char *) calloc (1, lenlt+tlen2+1)) == '\0’) 
return (-1); /* unable to allocate memory */ 
for (i = 0; i < start index; ++i) 
temp[i] = s2[i]; 


for (j = 0; temp[it] Sls as 


, . 


while (temp[it+j] = s2[i]}) 
tc 
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for (i = 0; (s2[i] = temp[i]) && i < maxchar; it?) 


e 
L4 


free (temp); 


if (i == maxchar && s2[il) /* insertion is inecompleto */ 
{ 
s2[i] = ’\0’; 
return (1); 
else 
return (0); 


String Insertion 


One of the keys to successful input-and-output (I/O) routines is the 
ability to insert one series of characters into another. The routine 
fast—insert does just that, but without bounds checking. If you are 
sure that inserting the new characters within the target string will 
not exceed the required storage space, this routine will indeed pro- 
vide excellent performance. If you are not sure of this, you should 
use the routine insert—string instead. 


char *s1="DEF"” 
char *s2=""—ABCGHI" fast insert "“ABCDEFGHI” 
int index =3 
O Successful 
—1 Insufficient memory 


Warning: fast—insert does not perform bounds checking. 


int fast_insert (source, target, index) 


Insert the contents of the source string to the target 
at the index location specified. 


Sl (in): source string containing characters to copy. 
s2 (out): string receiving characters copied. 
index (in): location within target to insert sl at. 


fast_insert ("Pocket", stringvar, 6); 
fast_insert does not perform bounds checking. If an error 


occurs during processing, fast_insert returns -1. If the 
insertion is successful, fast_insert returns 0. 


+ + + FF FF FF HF HF HF HF FH HK 
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int fast_insert (char sl[], char s2[], int start_index) 


{ 
int iy J, Lenly lLen2? 


char *temp; 
void *calloc(unsigned, unsigned) ; 


for (lenl = 0; sl{lenl]; ++lenl1) /* get the length of sl */ 


e 
t 


for (len2 = 0; s2[len2]; ++len2) /* get the length of s2 */ 


if (start _index > len2) start _index = len2; /* append * / 


if ((temp = (char *) calloc (1, lenl+len2+1)) == ’\0’) 
return (-1); /* unable to allocate memory */ 


for (i = 0; i < start_index; ++i) 
temp[i] = s2[i]; 


for (j = 0; temp[it+j] = sl(j]- j++) 


s 


while (temp[i+j] = s2[i]) 
++1; 


for (i = 0; s2{i] = temp[i]; i++) 
free (temp) ; 


return (0); /* successful insertion xf 


If this routine cannot insert the string without overwriting the 
array bounds, it returns the value 1. If the routine cannot allocate 
sufficient memory, it returns —1. If the insertion is successful, the 
routine returns the value 0. | 


) 


char *s1="DEF” 
char *s2="ABCGHI” 
int index=3 
maxchar=sizeof(s2) 


insert—string >" ABCDEFGHI" 


O Successful 
1 Bounds error 
—1 Insufficient memory 
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insert _string (source, target, location, array bounds) 


Insert the contents of the source string to the target 
at the index location specified. 


$1 (in): source string containing characters to copy. 

s2 (out): string receiving characters copied. 

index (in): location within target to insert sl at. 

maxchar (in): maximum number of characters in s2. 

insert string ("Pocket", stringvar, 6, sizeof (stringvar) ); 


insert _string returns one of the following: 
-l1 insufficient memory 0 successful insertion 1 incomplete 


/ 
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int insert string (char sl[], char s2[], int start_index, int maxchar) 
{ 
int i, j, lenl, len2; 


char *temp; 
void *calloc(unsigned, unsigned) ; 


for (lenl = 0; sl{lenl); ++lenl1) /* get length of sl */ 


tf 


0; s2(len2); ++len2) /* get length of s2 */ 


for (len2 


if (start_index > len2) start_index = len2; /* append */ 


if ((temp = (char *) calloc (1, lenl+len2+1)) == ’\0’) 
return (-1); /* unable to allocate memory */ 


for (i = 0; i < start_index; ++i) 
temp[i] = s2[i]; 


for (j = 0; temp[it+j] = sl[j3]; j++) 


s 


while (temp[itj] = s2[i]) 
++i; 


for (i = 0; (s2[i] = temp[{i]) && i < maxchar; i++) 


free (temp); 


if (i == maxchar && s2[i]) /* insertion is incomplete */ 
{ 
s2[i] = ’\0'; 
return (1); 


} 
else 
return (0); 
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Case Manipulation 


Many programmers often choose to convert a string of characters to 
either uppercase or lowercase in order to simplify future processing. 
Although the methods for converting characters in this manner are 
many, you can use a simple fact about ASCII characters to speed up 
conversion routines: All ASCII characters use a byte (8 bits) of stor- 
age. The sixth-bit location determines the character’s case. For 
example, if you examine the lowercase letter a” 


"a!" ASCII 97 Binaee 0110 0001 
along with the character A,” 
“AN ASCII 65 Binary 0100 0001 
you note that the only difference between them is the sixth bit: 


Mae! ines 0110 0001 
"A" Binary 0100 0001 


With this in mind, you can use Cc bitwise operators to perform quick 
comparisons: 


'A' 32 —. ‘a! 
0100 0001 | 0010 0000 = 0110 0001 © 


‘a’ & ~32 = 'A' : 
0110 0001 & 1101 1111 = 0100 0001 


The following routines convert a character scans from upper- 
case to lowercase, and vice versa: | 
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char *s= "AAA" we str__to__lowercase |= “aaa” 


void str_to_ uppercase (s) 

Convert a string to UPPERCASE characters. 

s (in/out): string to convert to UPPERCASE. 
str to uppercase (filename) ; 


str to uppercase uses bit manipulation to convert characters 
to uppercase. 


; 
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void str_to_uppercase (char s[]) 


2G. 5 
for (i = 0; s[i); 1++) 
if (s{i] >= ‘af && s[{ij] <= ’2") 
s{i) = s[i] & ~32; 


char *s= "aaa" —e| str__to__uppercase ae "AAAA" 


void str_to lowercase (s) 

Convert a string to lowercase characters. 

s (in/out): string to convert to lowercase. 
str _to_ lowercase (filename) ; 


str_to_ lowercase uses bit manipulation to convert characters 
to lowercase. 


/ 


+ + + + SF HF HF H F HH HF HF F 


void str _to_ lowercase (char s[]) 
{ 


int i; 
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for (i = 0; s[i]; i++) 
if (s[i] >= ‘A’ && s[i] <= '2Z2’) 
s{i] = s[{i] | 32; 


String Reversal 


When a program manipulates a mathematical expression as a 
string, the result shows the string reversed. Just as you have many 
ways to convert a string from uppercase to lowercase, you also have 
many ways to reverse the contents of a character string. 

Consider two alternatives. The first method, reverse—string, 
begins swapping characters in the string starting with the first and 
last characters, then the second and next to last, and so on. This 
effective method results in 1.5 * n exchanges, where n is the number 
of array elements. | 


char *s="EDCBA" " ABCDE” 


void reverse string (s) 

Reverse the contents of the character string specified. 
s (in/out): string to reverse the contents of. 

reverse string (binary result); 

This method requires 1.5 * n exchanges. 


/ 
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void reverse string (char s[{]) 
{ 
char temp; 


int i, 4; 


for (j = 0; s[{j]*f ++3) /* find the end of string */ 


s 
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TOL, Aa 0p: ery DOR ig ey) 


temp = s[ilJ; 
s{i] = s{jl; 
s[j] = temp; 


The second method has additional overhead in the form of a call 
to allocate memory large enough to buffer the string contents. Once 
this space is allocated, the first string is simply copied to the buffer 
and then back to the string in reverse order. 


™ 
* 


int reverse string (s) 

Reverse the contents of the character string specified. 
s (in/out): string to reverse the contents of. 

result = reverse string (binary result); 


This method requires 2.0 * n exchanges. If an error in 
processing occurs, reverse string returns -1. 


/ 
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int reverse string (char s[}) 
{ 


char *temp; 
void *calloc (unsigned, unsigned); 


int i, 34; 


for (4-= 07 silols +4) /* find the end of string */ 
if ((temp = (char *) calloc (1, 4j)) == ’\0") 
return (-1); /* couldn’t allocate memory */ 


° 


s 


So a ee) am ce As eT a ed 
temp[i] = s[j] 

0; 3 < as 3H) 

temp [J]; 


for 
s[j] 


return (0); 

This method results in 2 * n exchanges. 

Given a string of 512 characters, the first method requires 768 
exchanges, while the second method requires 1024. The first method 
is clearly superior. Your algorithm decision (even for simple rou- 
tines) can have a significant impact on the performance of your 
program. 
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Exchanging Strings 


Based on the preceding analysis of the string reverse routine, you 
can conclude that the fastest way to exchange two strings is by using 
a three-variable swap (see Figure 2-4). 


— 


0 


\ 


Figure 2-4. Three-variable swap 
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The following routines do just that. However, you must again 
consider the possibility that the user did not allocate the same 
amount of space for each string, as shown here: 


char s1[32], s2{64]; 


To exchange two strings whose boundaries are not identical 
could have devastating results. Again, you have two alternative 
routines —fast__exchange, which does not perform bounds checking, 
and string__exchange, which does. 


char *s1="AAAA" we : "BBBB" 
char «s2="BBBB” Behe ae "AAA" 


Warning: fast—__exchange does not perform bounds checking. 


void fast_exchange (sl, s2) 
Exchange the characters contained in two character strings. 


sl (in/out): contains characters to exchange. 
s2 (in/out): contains characters to exchange. 


fast_exchange (oldname, newname) ; 


/ 
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void fast_exchange (char sl[{], char s2[]) 


LC 246 -3e 
char temp; 
for (i = 0; sl[i] && s2[i]; itt) 


{ 
temp = sl[il; 


sl{i] = s2[il; 
s2[i] = temp; 

} 

if (sl[i}) 

{ 

er ay 
while (sl1[i]) 

s2{i] = sl[itt]; 


s2[i] = ‘\0’; 
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SULI) = 2 NO" 


else if (s2[i]) 
{ 
j = i; 
while (s2[i]) 
slf{i] = s2[itt+]; 
si({i] = '\0'; 
s2[j] = ’\0'; 
} 


_ The following routine performs bounds checking, which pre- 
vents it from exceeding the array bounds: 


char *s1="AAAA" "BBBB" 
char *s2="BBBB” — "AAAA" 
int size1=sizeof(s1) string__exchange 

int size2=sizeof(s2) 


0 Successful 
1 Bounds error 


string_exchange (sl, s2, sizel, size2) 

Exchange the contents of two character strings. 

si (in/out): contains characters to exchange. 

s2 (in/out): contains characters to exchange. 

sizel (in): maximum number of characters in sl. 

size2 (in): maximum number of characters in s2. 

result = string exchange (name, a, sizeof (name), sizeof (a)); 


string exchange returns one of the following: 
0 successful exchange -1 Insufficient memory 1 Incomplete 


/ 
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int string exchange (char sl[], char s2[], int sizel, int size2) 
int i, 3 | | 
char temp; 
for (i = 0; sl[i]; i++) /* get length of si */ 


’ 
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if (i >= size2) /* too large for s2 ? */ 
return (1); 


for (i = 0; s2[i]; it+) /* get length of s2 */ 


tA 


if (i >= sizel) /* too large for sl ? */ 
return (1); 


for (i = 0; sl[i] && s2[i]; itt) 
{ 
temp = sl{il]J; 


sl[{i] = s2[i]; 
s2[{i] = temp; 
if (sli[i)) 
{ 


J = 1; 

while (sl[i]) 
s2[{i] = sl[it+t]; 

S2[i] S-"\0"3 

sl[j] = '\0’'; 


} 
else if (s2[i]) 
{ 
jai; _ 
while (s2[i]) 
sl{i] = s2[it++]; 
sl[{i] = ’\0'; 
s2(j] = '\0'; 


return (0); 
} 


If the exchange is successful, the routine returns the value 0. If 
one string contained too many characters, the routine returns the 
value 1. 


String Padding 


Many reports that appear aligned on the computer screen often 
require one or two leading blanks so that they will be aligned prop- 
erly on printed output. The following routine enables you to place 
additional blanks in front of a string. Once again, bounds checking 
is a concern when producing the routines fast__pad and pad__string, 
as shown here: 
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char *s1="AAA" "AAA" 


int num__blanks=3 


fast__ pad 


|__» O Successful 
-1 Insufficient memory 


Warning: fast—_pad does not perform bounds checking. 


int fast_pad (s, num_blanks) 


Place the number of blanks specified at the front of a 
string. 


s (in/out): string to pad 
num blanks (in): number of blanks to insert. 


result = fast pad (s, 33);7 


pad string returns the value -1 if insufficient memory 
prevented the insertion. 


/ 


* + HF HF HF FH HF HH eH HF HF 


int fast _pad (char s[], int num blanks) 
{ 4 ; 
Ime wy he 
char *temp; 


void *calloc(unsigned, unsigned); 


for (i = 0; s[i]; i++) /* get the length of s */ 


v 


if «(temp =- (char *) -calloc. (1, i+ num blanks + 1)) == ’\0") 
return (-1); /* couldn’t get memory */ 


for (i = 0; i < num_blanks; i++) 
temp [i] = ’ '; 


for (j = 0; temp [i] = s[j]s ++3, ++) 


temp [i] = ’\0’; 


for (i = 0; s[i] = temp[i]; i++) 


free (temp); 


return (0); 
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If the padding is successful, the following routine returns the value 
0. If insufficient memory is available, the routine returns a value —1. 
If the array bounds are exceeded, the routine returns 1. 


char *s1="AAA” 
int num__blanks== 
int maxchar=sizeof(s1) 


"AAA" 
pad_ string 


0 Successful 
1 Bounds error 
—1 Insufficient memory 


int pad_string (s, num blanks, maxchar) 


Place the number of blanks specified at the front of a 
string. 


Ss (in/out): string to pad 
num blanks (in): number of blanks to insert. 
Maxchar (in): maximum number of characters in s. 


result = pad string (s, 33, sizeof (s)); 


pad_ string returns one of the following values: 
-1 Insufficient Memory O Successful 1 Incomplete 


/ 
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int pad_string (char s[], int num_blanks, int maxchar) 


{ 
28 9) Samo raaiey 
char *temp; 


void *calloc(unsigned, unsigned) ; 


for (1 = 07: sia]? a+) /* get length of s */ 


° 
, 


if (i + num_blanks >= maxchar) /* will blanks fit */ 
return (1); 


else if ((temp = (char *) cailoc (1, i + num _ blanks + 1)) == ’\0’) 
return (-1); | /* can’t get memory */ 

for (i = 0; i < num _ blanks; i++) 
temp [i] =!’ '; 


for (i = OF cemp. (he sia “ee ay Fe) 


e 
v 
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temp [i] = ’\0’; 
for (i = 0; s[{i] = temp[i]; itt) 
free (temp); 


return (0); 


Character Manipulation 


Before discussing the more difficult routines that perform string 
comparisons and substring matching, you should first consider rou- 
tines that manipulate a single character within a string. The follow- 
ing routines locate, replace, or delete a specific character within a 
string. | 

The first function, char—_count, returns the number of occur- 
rences of a character within a string: 


char—count 


3 A occurs three times in AAAaaa 
0 If letter not found 


char *s="AAAaaa” 
char letter='A’ 


char count (s, letter) 
Return the number of occurrences of letter in s. 


Ss (in): string to search. 
letter (in): letter to search for. 


count = char cnt ("This is a test", 's’); 


/ 
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char _count (char s[], char letter) 
{ 


int i, count = 0; 
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for (i = 0; s[i]l; itt) 
if (s[i] == letter) 
count++; 


return (count); 


Similarly, the routine remove—character removes each occurrence 
of the specified character: 


char *s="AaAaAa” "AAA" 
char letter='a’ remove _—character 


O Successful 
—1 Insufficient memory 


remove character (s, letter) 
Remove each occurrence of letter from s. 


s (in/out): string to remove the letter from. 
letter (in): letter to remove. 


remove character (s, ‘a’); 


remove character returns the value -1 if insuffient memory 
prevented the removal, otherwise, 0. 


/ 
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int remove character (char s[], char letter) 


{ 


Int a5 
char *temp; 
void *calloc(unsigned, unsigned) ; 


for (i = 0; s{i]; i++) 
if ((temp = (char *) calloc (1, i)) == ’\0") 
return (-1); 


for (i = 0, j = O; si]; itt) 
if (s{i] != letter) 
temp[j++] = s[il]; 


38 


TURBO C PROGRAMMER’S LIBRARY 


for (temp[j] = ’\0’, i = 0; s[{i] = temp[i]; i++) 


free (temp); 


return (0); 


The function char_—index returns the first occurrence of a char- 
acter string within a string. If the character is not found, the routine 
returns the value —1. 


char *s="ABab” 


ee char_—index 
char letter=‘a 


2 aisat offset 2 
—1 If letter not found 


char_index (s, letter) 
Return the location of the first occurrence of letter in s. 


s (in): string to search for letter. 
letter (in): letter to search for. 


index = char_index (s, letter); 
char_index returns -1 if the letter is not found. 


/ 
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int char_index (char s[], char letter) 


int i, location = -1;; 
for (i = 0; s[i] && (location == -1); i++) 
if (s{i] == letter) 


location = i; 


return (location); {/*® =) TLEonoe Pound. +7 


Similarly, the routine right__char—index returns the last occur- 
rence of the character specified in a string or the value —1 if the 
character is not found. 
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char *s="ABAB" 


right__char__index 
char letter='A’ g 


2 Second A appears at offset 2 
—1 If letter not found 


right_char index (s, letter) 
Returns the rightmost occurrence of letter in s. 


s (in): string to search for the letter. 
letter (in): letter to search for. 


result = right _char_index (s, 'A’); 
right_char_index returns -1 if the letter is not found. 


/ 


+ + + F HF FF HF HF F KF FF OF 


int right_char_index (char s[], char letter) 
{ 
int i, location = -1; 


for {i °="03.s[i)}} i++) 
if (s{i] == letter) 
location = i; 


return (location); /* -1 if not found */ 


} 


The routine replace—char replaces each occurrence of the first 
specified character with the second specified character. 


Char *s="Hill” “Hall” 
Char letter 1='I' replace_—char 


char letter2='a’’ 


void char replace (s, source letter, target_letter) 


Replace each occurrence of source letter with target_letter 
within the string s. 


* + + + HF 
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s (in/out): string to replace characters in. 
source letter (in): letter to replace. 
target_letter (in): replacement letter. 

char replace (s, ‘A’, '’a’'); 


i 
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void char replace (s, source letter, target letter) 
char s[]; . 
int source letter, target_letter; 


{ 


int i; 
if (source letter != target_letter) 
for (i = 0; s[i]; itt) 
if (s{i] == source letter) 
s[i] = target _letter; 


The routine fill—string fills a character string with a specific 
number of occurrences of the specified character. The routine per- 
forms bounds checking to ensure that it does not overwrite the array 
bounds. If the assignment is successful, the routine returns the value 
0. Otherwise, the routine returns the value 1. 


char *s="——" | "AAAAA" 
char letter='A’ 

int count=5 fill__string 

omy ,scvjst=sizeof(s) 


O Successful 
1 Bounds error 


fill string (s, letter, count, maxchar) 
Place count occurrences of letter into the string s. 


Ss: (in/out): string to fil. 

letter (in): letter to place into the string. 
count (in): number of times to insert the letter. 
maxchar (in): maximum number of characters in s. 


+ + + + + FH FH FH OF 


fill string (s, ‘A’, 10, sizeof (s)); 
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* fill string returns 1 if the fill was unsuccessful, 0 if 


* successful. 
* 


va 
int fill string (char s[], int letter, int count, int maxchar) 
int i; 
if (count+l > maxchar) /* +1 reserves space for null */ 
return. (1)? /* insufficient memory */ 
for (i = 0; i < count; ++i) /* fill the string */ 
s{i] = letter; 
s[ijo= 7X0"; 


return (0); 


White Space 


Programmers who use C often define white space as either the 
blank character (ASCII 32) or the tab character (ASCII 9). Just as 
your programs require you to place blank characters at the start of 
character strings, they periodically require that you remove them. 
The following routines allow you to locate the first and last 
nonwhite-space character in a string. The first function, called 
first—nonwhite, returns the location of the first character in the 
string that is not a white-space character, or the value —1 if the 
string contains solely white space. 


char *s="AAA” first_nonwhite 


0 First character is nonwhite space 
—1 If string contains only white space 


/* first_nonwhite (s) 
* 


* Return the index of the first character that is not white 


42 TURBO C PROGRAMMER’S LIBRARY 


: space (a blank or a tab). 

: s (in): Serna es examine for nonwhite space. 

* result = first_nonwhite (name) ; 

* If the string contains all white space, -1 is returned. 
i . 


int first_nonwhite (char s[]) 


int i, location = -l; | 
for (i = 0; s[i] && (location == -1); ++i) 
if ((s{i) t=" ') && ts[i}) t= “\t")) 
location = i; 
return (location); /* -1 if all white space */ 


} 


Similarly, the routine last_nonwhite returns the location of the last 
nonwhite-space character in the string, or the value —1 if the string 
| contains only white space. 


char *s="AAA" last__nonwhite 


O Last character is nonwhite space 
—1 If string contains only white space 


(7 = eae Monwhsee (s) 

* Return the index of the last character that is not white 
: space (a blank or a tab). 

fl s (in): string to examine for nonwhite space. 

: result = last_nonwhite (name); 

< If the string contains all white space, -1 is returned. 
x 


/ 

int last_nonwhite (char s[]) 
int i, location = -1; 

for (i = 0; s[i]; ++i) — 


if ((sf{i] !=/' ’) && (s[i] != ’\t’)) 
location = i; 
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return (location); /* -1 if all white space */ 


String Comparison 


Most applications that perform string manipulation eventually must 
perform string comparisons. Many existing routines will help you 
determine whether two strings are equal. For example, consider this 
loop, which compares two strings: 


for: (i = 0; ‘si [a 
af (Sl fi) e=°* 
{ 


printf ("Equal strings\n"); 
break; 
} 


The routine begins with the first letter in each string and compares 
them. As long as the letters are equal, the routine compares succeed- 
ing characters. This process continues until either two characters 
are not equal, or the ends of both strings are found. 

Consider these examples: 


Equal strings 


Not equal 


44 TURBO C PROGRAMMER’S LIBRARY 


Although this routine works, often the program would like the 
strings to be considered equal, regardless of the case of the letters. 
Here, the routine should show the strings "Turbo C” and "TURBO 
C” as equivalent. In order to support the capability to perform case- 
sensitive comparisons, you must add a third parameter, as shown 
here: | 


equal strings (sl, s2, ignore case); 


Thus, one routine serves both possible requirements of the user. 
The following routine returns the value 1 if the two strings are 
equal, and 0 otherwise. It supports case-sensitive processing. 


char *s1="AAA" 
char *s2="aaa"” equal_—strings 
int ignore__case=1 


-1 Equal strings 
~Q Not equal strings 


equal strings (sl, $2, ignore_case) 


Return 1 if the strings sl and s2 are equal, otherwise return 
0. Support case sensitive processing. 


sl (in): string to compare. 

s2 (in): string to compare. 

ignore case (in): if not 0, case of letters is ignored. 
if (equal_strings ("THIS", "this", 1) ) 


equal strings returns 1 if the strings are equal, 0 
otherwise. 


/ 
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int equal strings (char sl[{], char s2[], int ignore case) 


int i; 
char a, b; 
for (i = 0; sl[i] && s2[i]; itt) 


if (slf{i] != s2{i)) 
{ 
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if (ignore case) 


{ 


a = (sl({i) >= ’a’ && slf[i}] <= '’z’) ? si[i] & ~32: si[i]; 
b= (s2 [ij c=" a’ && s2(2) <=] "2") 2 s2[il ©& ~32¢ -s2 [ile 
if (a != b) 
break; 
} 
else 
break; 
} 
if (sl{i) II s2[i]) 
return (0); 


else 
return (1); 
} 


Similarly, the following routine returns the location of the first 
character that differs between two strings, or —1 if no difference 
occurs. This routine supports case-sensitive processing. 


char *s1="TEST” | 
char *s2="TEST"” first__ difference 
ing ignore__case=—0 


Index to first different character 
—1 If strings are equal 


™~ 
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first _difference (sl, s2, ignore case) 


Return the location of the first difference between two strings 
or the value -1 if the strings are equal. 


sl (in): string to compare. 
s2 (in): string to compare. 
ignore case (in): if 1, case is ignored. 


location, = first, ditterénce: ("This"™, “THIS™; 1); 
/ 


int first_difference (char sl[], char s2[], int ignore case) 
{ 
int i; 
char a, b; 
for (i = 0; sl[i] && s2[i]; i++) 


if (sl[{i] != s2{i]) 
{ 
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if (ignore case) 


a = (sl{i] >= ’a’ && sl[i] <= ’z’) ? sl[i] & ~32: sl{[i]; 
b = (s2[i] >= ’a’ && s2[i] <= 'z’) ? s2[i] & ~32: s2[i]; 
if (a != b) 
break; 
else 
break; 
} 
if (sl{i] || s2[i)) 
.» return (i); 


else 
return (-1); 
} 


The routine string—_comp examines two character strings and 
returns one of the following values: 


0 Strings are equal 
1 First string is greater 
2 Second string is greater 


char *s1="AAA” 
char *s2="AA” string __ compare 
int ignore__case=1; 


QO If strings are equal 
1 If st>s2 
2 If s2>s1 


/x 

* string comp (sl, s2, ignore case) 

* 

* Compare the strings specified. Return 1 if sl > s2, 2 if 
* s2 > sl and 0 if the strings are equal. Support case sensitive 
: processing. 

* sl (in): string to compare. 

* s2 (in): string to compare. 

* ignore case (in): if not 0, case of letters is ignored. 
‘ 

* if (string.comp ("THIS", "this", 1) == 1) 

* 

* 
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int string comp (char sl[], char s2[], int ignore case) 
{ 

int <2) 

char a, b; 

int result = 0; 


for (i = 0; sl{i] && s2[i]; i++) 
if (sl[{ij) != s2[i]) 
{ 


if (ignore case) 


{ 


a= (sl{i) >= ’a’ && sl[i] <= 'z’) ? sl[i] & ~32: 
b = (s2[i) >= ’a’ && s2[i] <= ’z’) ? s2[i] & ~32: 
if (a !=b) 
{ 
if (a > b) 
result = 1; 
else 
result = 2; 
break; 
 } 
} 
else 


{ 
if (sl[{i] > s2[i}) 
result = 1; 
else 
result = 2; 


break; 
} 
} 
if (result == 0) 
{ 
if (si[ij) == s2[i)) 


result = 0; 


else if (sl[i]}) 
result = 1; 
else 
result = 2; 


return (result); 


Substring Manipulation 


/* 0 equal, 1 sl greater, 2 s2 greater */ 


siti; 
s2(2]; 


A7 


Just as a character string is a sequence of characters, a substring is 
a series of characters within a string. For example, given the string 
“Turbo C Programmer’s Library”, “Turbo” is a five-character sub- 


string that begins at offset 0. 


The following routines enable you to locate, eaplace and count 
the number of occurrences of a substring within a string. The first 
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routine, str__index, returns the starting offset of a substring within 
a string, or the value —1 if the substring is not found. 

Given the string “McGraw-Hill” and the substring “Hill”, the 
routine processes as follows: | 


L. inckemient the index until string[index F=substring[0], or the 
end of the string is found (see Figure 2-5). 


2. Increment the index of the string and substring as long as 
the corresponding letters are equal, or until the end of either 
string 1s found (see Figure 2-6). 


3. If the substring is found, return the index within the string 
that corresponds to the start of the substring. Otherwise, 
resume Step 1. | 


substring[0] 


string[7] 


Figure 2-5. Incrementing the index 
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substring[0] 
substring[1] 

substring[2] ||| 
substring[3] ae 
substring[4] 


string[7] 
string[8] 
string[9] 
string[10] 
string[11] 


Figure 2-6. Incrementing the index until length of string and 
substring are equal, or until end of string 


This code implements str—index: 


char *str="THIS” str___index 
char *sub="IS” 


2 Index at which substring begins 
—1 If substring is not found 
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index (substring, string) 


Return the starting index of the substring within a string 
or the value -1 if the substring is not found. 


substring (in): substring to search for. 
String (in): string to examine. 


if (index ("PATH=", *ENV[1]) != -1) 


/ 
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int index (char substr[], char str[]) 
{ 


intl; ye KF 


for (1 = O; str[i]; i++) 
for (j = i, k = 0; str[(j] == substr{k]; jtt+, ktt+) 
if (! substr[k+1}) /* end of substring */ 
return (i); 


return. (-1):; fk substring not found */ 


} 


Similarly, the following routine returns a count of the number of 
times that a substring appears in a string: 


char *str="THIS IS" 


ahaa? str—count 
char «sub="IS 


2 IS appears twice 
O If substring not found 


/ * 
* str count (substring, string) 
k : 
* Return the number of occurrences of the substring within 
* the string specified. 
*k 
* substring (in): substring to search for. 
* string (in): string to examine. 
* 
* count = str count ("is", "This is a test"); 
k 
x 
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int str count (char substr[], char str[]) 
{ 


int; Jy ky scount = 104 


for (i = 0; str[{i]; it+) 


for (j = i, k = 0; str[j) == substr[{k]; j++, k++) 
if (! substr[k+1]) /*x end of substring */ 
countt++; 
return (count) ; /* 0 if string not found */ 


} 


The routine remove—substring deletes each occurrence of a 
substring from a string: 


char *str=""AABBCC"” 
char *sub=""BB” —_ 


remove_—substring 


O Successful 
—1 Substring not found 


les 

* remove substring (substring, string) 

* 

x Removes the first occurrence of a substring from within a string. 
* 

* substring (in): substring to remove. 

* string (in/out): string to remove the substring from. 

* 

* status = remove substring ("is", strvar); 

x 

* If successful, remove_substring returns the value 0. If the 

* substring is not found, remove_substring returns the value -l. 
* 

* 


/ 


int remove substring (char substr[{], char str[]) 


{ 


TNC ay op Ke ecation. = 1; 
for (i = 0; str[i] && (location == -1); i++) 
for (j = i, k = 0; str[j] == substr[k]; j++, k++) 
if (! substr[k+1]) /* end of substring */ 


location = i; 


if (location != -1) 
{ e 
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for (k = 0; substr[k]; k++) 


e 


for (j = location, i = location + k; str{i]; j++, itt) 
str[{j] = str[i]; 


str[j] = ‘\0’; 


return (0); 
} 
else 


return (-1); /* substring not found */ 


The routine next—str—occurrence returns the next occurrence 
of a substring within a string that follows the index given. If the 
substring is not found, the routine returns the value —1. 


char «str="THIS IS” 
char *sub="1IS”"” next__str__occurrence 
int index=4 


5 Starting index of next 
occurrence of the substring 
—1 If not found 


next_str occurrence (substring, string, start _index) 


Return the index of the next occurrence of the substring 
within the string starting at the index specified. 


Substring (in): substring to search for. 

String (in): string to examine. 

index (in): starting index of the search. 

location = next_str_occurrence ("is", “this is a test", 4); 


If the substring is not found, -1 is returned. 


/ 
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int next_str_occurrence (char substr[], char str[], int index) 
{ | 
int i, Jj, k; 


for (i = index; str[i]; i++) 
for (j = i, k = 0; str[j]) == substr[(k]; j++, k+t) 
if (! substr[k+1]) /* end of substring */ 
return (i); . 
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return (-1); /* substring not found */ 
} 


Pattern Matching 


The last obstacle facing the completion of your library of string- 
manipulation routines is the matching of wildcard characters. For 
example, assume that you are concerned with only the first and last 
three letters of a file named ABC??FGH. Since you do not care about 
the middle two characters, they are replaced with question marks. 
With the routines just shown, you can modify the search loops, as 
shown here: 


char«str=""THIS” 


char*sub= "9921S" pattern— index 


Index where substring starts 
—1 If substring is not found 


pattern_index (substring, string) 

Return the starting index of the substring within the string. 
Allow the user to place the ? wildcard character within the 
substring for "don’t care" letters. 

pattern _ index ("this ???", "this bbb a test"); 


If the substring is not found, pattern_index returns -1. 


‘A 
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int pattern_index (substr, str) 
char substr[], str[]; 
{ 
int i, j, k; 
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for (i = O; str[i]; itt) 
for (j = i, k = 0; (str{j] == substr[k]) 
|| (substr[k] == '2'’); jt+t, kt+t) 
if (! substr[k+1]}) /* end of substring x / 


return (1); 


return (-1); /* substring not found */ 


This simple addition adds considerable flexibility to your routines. 


Pownter 
Manipulation 


Chapter 2 created a valuable library of string-manipulation rou- 
tines. To do so, each string was treated as an array of characters, as 
shown here: 


char s[{100]; 


Although each of the character array routines is fully functional, 
you can in many cases reduce to an even greater extent the amount 
of code required to implement each routine by using pointers. Many 
C programs make extensive use of pointers, so you must understand 
them. 

By the end of this chapter, you should feel comfortable with the 
use and manipulation of pointers. In fact, you will be developing 
pointer-manipulation routines that possess tremendous capabilities. 


5D 
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Getting Started 


All of the variables that you use in your programs are stored in 
memory. In order to be able to access each specific variable, C must 
have a means of differentiating variables (see Figure 3-1). C does 
this by assigning each variable a unique memory address, as shown 
in Figure 3-2. 

The C ampersand operator (&) returns a variable’s address. 
Note that the following program does not display the value each vari- 
able contains, but rather the location of each variable in memory: 


main () 
int a = 5, b = 10; 


printf ("Address of a %u -- Address of b %u\n", 
&a, &D); 


By adding a simple modification to the program, you can dis- 
play the address and value of each variable, as shown here: 


main () 
int a = 5, b = 10; 


printf ("Address of a %u Value %d\n", &a, a); 
printf ("Address of b %u Value %d\n", &b, b); 
} | 


A pointer is a variable that contains a memory address. To 
declare a pointer variable, use the following format: 


variable type *variable name; 


For example, to declare a pointer to a value of type int, use the 
following: 


int *int_pointer; 


The asterisk tells C that the variable is a pointer to a memory 
location that contains a value of type int. To assign an address to the 
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pointer, use the ampersand operator, as shown here: 


int_pointer = &integer variable; 


Notice the absence of the asterisk (*). When a program refer- 
ences a pointer without an asterisk, it is referring to a memory 
address. For example, in the previous assignment you were assign- 
ing the address of the variable integer_variable to the pointer 
int__pointer, so no asterisk was used. When an asterisk is used with 
a pointer, the value contained at the memory location referenced by 
the pointer is manipulated (as opposed to the address). 

Consider the following example: 


main () 
int i, *int_pointer; 
int_pointer = &i; 


*int pointer = 5; 


This program begins by assigning the address of 7 to the pointer 
int_pointer. Following this assignment, int_pointer contains the 
memory address of 7. | 


Address 


1024 1024 int—pointer 


*int_pointer=5; 


_Memory 
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a 
main() 
b 
6 
int a,b,c; 
j 
Memory 
Figure 3-1. Differentiating among variables 
Address 
1000 a 
f | 1004 C 
int a,b,c; 
} 
‘Memory 


Figure 3 -2, Assigning variables unique memory addresses 


POINTER MANIPULATION 59 


You can verify this by adding the following line of code: 


printf ("Address of i tu Value of int_pointer\n", 
&i, int_pointer) ; 


Next, the program assigns the value 5 to the memory location 
referenced by znt_pointer. 


Address 


1024 i 1024 int_pointer 


*int_pointer=5; 


In so doing, the variable 7 (which also refers to the same memory 
location) is assigned the value 5. 


Pownters and Functions 


Chapter 2 examined several functions that returned a status value 
indicating the success of their processing. In cases such as this 
where the function needs to return only one value, you have no addi- 
tional processing concerns. For example, the following function 
returns the sum of two integer values: 


sum (int a, int b) 


return (a + b); 
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In this case, the function returns one value and cannot modify the 
contents of its parameters. 

C passes parameters to functions by using a technique awa as 
call by value. Each time a parameter is passed to a function, C 
assigns a copy of the value in the parameter to the function parame- 
ters (formal parameters). Consider the following program, which 
passes two integer variables to a function. The function first dis- 
plays the original values and then modifies each of the parameter 
values. However, when the program control returns to main, the 
original variable values. remain unchanged because the function 
modified copies of the values contained in the variables (as opposed 
to the variables themselves). 


main () 
int a = 5, b = 10; 
some_function (a, b); 


printf ("In main a = %d b = %$d\n", a, b); 
} 


some function (int a,’ int b) 
printf ("In some_function a = %d b = %d\n", a, b); 


9; 
11; 


a 
b 


printf ("In some function a = %d b = %d\n", a, b); 


On invocation, this program displays the following: 


In some function a 


In some function a 
In main a=5b 


If you want to modify the actual parameters within a function, 
you must use pointers. For example, assume that you have two vari- 
ables (a and b) that you want to initialize by using a function. To do 
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So, you must pass the addresses of each variable to the function by 
using the ampersand operator, as shown here: 


main () 
int a, b; 
initialize (&a, &b); 


printf ("a = $d b= $d\n", a, b); 
} 


Within the function, you must specify to C that you are using point- 
ers, as shown here: 


initialize (int *a, int *b) 


*a 
*b 
} 


1 
Zs 


On invocation, this program displays the following: 


This is because the function variables referenced the same memory 
locations as the actual parameters (see Figure 3-8). 

In a similar manner, the following function increments all three 
of its parameters: 


increment (int *a, int *b, int *c) 
(*at) +; 
(*b) ++; 
(*c) ++; 


} 


Once again, invoke the function as follows: 


increment (&valuel, &value2, &value3); 
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main() 


{ 
int a,b; 
initialize(&a,&b): = 
e ———— 


j 


-initialize(a,b) 


7 Memory 
int *a,*b; 


Figure 3-3. Variables referencing same memory locations 
as parameters 


Pointers and Strings 


Probably the greatest use of pointers in C is for string manipulation. 
Each time C passes an array to a function, it passes the address of 
the first element in the array. Remember, strings in C are treated as 
arrays. | 
Since you are dealing with memory addresses, this provides an 
ideal application for pointers. Consider the following function, which 
displays the first character in the array of characters that it 
receives: 


show first (char *s) 


{ 
printf ("%c\n", *s); 
} 
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Address 


Figure 3-4. References of s in "Turbo C” string 


On invocation, s points to the first letter in the string. Assuming that 
the string is "Turbo C”, s references as shown in Figure 3-4. If you 
simply add 1 to the memory address, you can point to the second 
letter in the string, as shown here: 


show_second (char *s) 


stt; /* point to second character */ 
Printr® <“te\n"; °“*s)> 


The following routine displays the contents of the string it 
receives: 


show_string (char *s) 
{ 
while (*s != ’\0’) 
{ 


printf ("%c", *s); 
Stt+; 
} 
} 
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With each iteration, you simply add 1 to the pointer (called incre- 
menting the address). 

Next, you can reduce the code to an even greater extent by using 
the following expression: 


*s++ 


In this case, C will first use the value contained in the memory 
address referenced by s and then increment it. As such, the code 
fragments | 


a = *st+; 


and 


a= *S; 
St+; 


perform identical functions. With this concept in mind, you can 
modify the code as shown here: 


show string (char *s) 
while (*s != ’\0‘) 
printf ("%c", *st++); 
} 


The following routines make extensive use of pointers. Many of 
these routines perform functions that are similar to the functions of 
routines presented in Chapter 2. You must understand the process- 
ing involved in the routines that follow. 


String-Manipulation Routines 


The first function, string—length, returns the number of characters 
in a string: 
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char *s1="Test” string—length 


4 Number of characters in the string 


string length (s) 

Return the number of characters in the string. 
s (in): string to count the characters in. 
length = string_length ("This is a test"); 

/ 
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string length (char *s) 
f : 
int len = 0; 


while (*st++) 
lent+t+; 


return (len); 


In a similar manner, the routine char_index returns the first 
occurrence of the letter specified within the string. If the letter is 
not found, char—_index returns the value —1. 


char *s="This is” 


at char—index 
char letter="i = 


2 index of the letter i in the string 
—1 If the letter is not found 
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char index (s, letter) 


Return the index of the first occurrence of letter in 
the character string specified. 


s (in): string to search for the letter. 
letter (in): character to search for. 


index value = char_index ("This is a test", 'i’); 


/ 
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char_index (char *s, char letter) 
{ . 
int count, location = -1; 


for (count 0; *s && (location == -1); count++) 


= r 
if (*st++ == letter) 
location = count; 


return. (location); 


—} 


The routine char_—count returns the number of occurrences of 
the letter specified within the string. If the letter is not found, 
char—count returns the value 0. | 


char *s="This is” , 
Char letter "ij" 


char—count 


2 Number of times i appears in the string 
O If letter not found 


char _ count (s, letter) 


Return the number of occurrences of a letter in the 
character string specified. . 


Ss (in): string to search for the letter. 
letter (in): character to search for. 


count = char_count ("This is a test", /’i!’); 
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char Count (Char *s;. char letter) 


{ 


inte count =04 


while (*s) 
if (*s++ == letter) 
countt++; 


return (count); 


} 


The function replace__character replaces each occurrence of the 
first letter specified in the first string with the letter contained in 
the second string. 


char *s="aaaBBB” "“AAABBB” 
char old="a" 


char new="A" 


replace—_character 


/* 
* void replace character (s, oldletter, newletter) 

* 

* Replace each occurrence of oldletter in a string with 
* the character contained in newletter. 

* 

* gs (in/out): string to replace the letters in. 

* oldletter (in): letter to replace. 

* newletter (in): replacement letter. 

* 

* replace character (some string, ‘A’, 'a’); 

* 

*/ 


void replace character (char *s, char oldletter, char newletter) 


{ 
while (*s) 


if (*s == oldletter) 
*st+ = newletter; 
else 
S++; 


In a manner similar to the routines in Chapter 2, the following 
routines use bit manipulation to convert a string to uppercase or 
lowercase letters: 
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char *s="aaabbb"—s| _str_to_uppercase [= "AAABBB” 


void str_to_uppercase (s) 

Convert a string to UPPERCASE characters. 

s (in/out): string to convert to UPPERCASE. 
str_to_ uppercase (filename) ; | 


str_to_ uppercase uses bit manipulation to convert characters 
to uppercase. 


/ 
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void str_to_uppercase (char *s) 
{ 
while (*s) : 
if (*s >= 'a’ && *s <= '2"’) 
*st+ &= ~32; 
else 
St++t+; 


char *s="AAABBB” "aaabbb" 


void str_to_ lowercase (s) 

Convert a string to lowercase characters. 

s (in/out): string to convert to lowercase. 
str_to lowercase (filename) ; 


str_to_ lowercase uses bit manipulation to convert characters 
to lowercase. 


/ 


+ + & FF HH HF HH HF eH HF 


void str_to_ lowercase (s) 
“char *s; 
{ 
while (*s) . 
if (*s >= ‘A’ && *s <= 'Z') 
“st? [=-32; 
else 
St+t+; 
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This routine copies the contents of the first string specified to 
the second string. This routine does not perform bounds checking. 


char *s1="AAAA” r , 
char *s2 fast_copy —e "AAAA 


Warning: fast—copy does not perform bounds checking. 


void fast_copy (source, target) 
Copy the contents of the source string to the target. 


sl (in): source string containing characters to copy. 
s2 (out): string receiving characters copied. 


fast_copy ("This is a test", stringvar); 
fast_copy does not perform bounds checking. 


/ 
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void fast_copy (sl, s2) 
char *sl, *s2; 
{ 
while (*s2++ = *s1+t+t) 


} 


You can implement bounds checking simply by adding the maxchar 
qualifier (as shown in Chapter 2): 


char *s1="AAAA" 
char *s2 copy—string |—» "AAAA” 


int maxchar=sizeof(s2) 


Successful 
Bounds error 


/* 
* int string copy (source, target, array bound) 
* 
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* Copy the source string to the target string variable. 

* 

* sl (in): contains the characters to be copied. 

* s2 (out): receives the characters copied. 

* maxchar (in): specifies the maximum number of characters 

ie that s2 can store. 

* 

* status = string copy ("This is", stringvar, sizeof (stringvar)); 
* : 

* If the array bounds are exceeded, string copy returns the value 
* 1; otherwise it returns the value 0. - 

; 

“7 


int string copy (char *sl, char *s2, int maxchar) 
{ 


oh oh same Oe 
maxchar--; /* leave space for null x / 


for (i = 0; (*s2++ = *sS1++) “&E& (i < maxchar); i++) , sae 


tf 


if ((i == maxchar) && *s1) /* see if characters remain in sl */ 
{ 
*Ss? = tN OT 
return (1); 
} 
else 
return (0); 


The routine fast—_append appends the contents of the first spec- 
ified string to the second string. No bounds checking is performed. 


char *si="CCC"” | : ; 
char *s2="AAABBB" fast_append +» "AAABBBCCC 


Warning: fast_append does not perform bounds checking. 


void fast_append (source, target) 
Append the contents of the source string to the target. 


sl (in): source string containing characters to append. 
s2 (out): string receiving characters copied. 


fast_append ("This is a test", stringvar) ; 
fast_append does not perform bounds checking. 


/ 
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void fast_append (char *sl, char *s2) 


{ 
while (*s2) /* find the end of s2 */ 
S2++; 


while (*s2++ = *sl++) /* append sl */ 


} 4‘ 


The following routines perform case-sensitive string compari- 
sons. 

The first routine, equal_strings, returns the value 1 if two 
strings are identical. Otherwise, it returns 0. 


char *s1="This” 
char *s2="THIS” equal__strings 
int ignore__case=1 


Strings are equal 
Strings differ 


/* 

* equal strings (sl, s2, ignore case) 

* 

* Return 1 if the strings sl and s2 are equal, otherwise return 
* Q. Support case sensitive processing. 

* 

* sl (in): string to compare. 

* s2 (in): string to compare. 

* ignore case (in): if not 0, case of letters is ignored. 
* 

* if (equal strings ("THIS", "this", 1)) 

* 

* equal _ strings returns 1 if the strings are equal, 0 

* otherwise. 

* 

*] 


int equal _strings (char *sl, char *s2, int ignore case) 
{ 
char a, b; 


for (; *sl && *S2 ; sSl++, S2++) 
if (*sl != *s2) 
{ 
if (ignore case) 
{ 
a (*sl >= al && *sl <= 'z’') ? *s1 & ~32: *s1; 
b (*s2 >= 'a’ && *S2 <= '2') 2? *S2 & ~32: *S2; 
1f (a != b) 
break; 


Ho 
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} 
else 
‘break; 
} 


if (*sl || *s2) 
return (0); 
else | 
return (1); 


The routine string—compare returns one of the following 
values: 


0 Strings are equal 
1 String 1 > String2 
2 String 1 < String2 


char *s1="THAT” 
char *s2="THIS” string—_compare 
int ignore__case=1 


string comp (sl, s2, ignore case) 

Compare the strings specified. Return 1 if sl > s2, 2 if _ 

s2 > sl and 0 if the strings are equal. Support case sensitive 
processing. 

sl (in): string to compare. 

s2 (in): string to compare. 

ignore case (in): if not 0, case of letters is ignored. 

if (string comp ("THIS", "this", 1) == 1) 


/ 
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int string comp (char *sl, char *s2, int ignore case) 
{ . 
char a, b; 
int result = 0; /* 0 equal, 1 sl greater, 2 s2 greater */ 


for (; *sl && *s2; slt++, s2++) 
if (*sl1 !=-*s2) 
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if (ignore case) 
{ 


a (*sl >= '’a’ && *S1 <= ’2z’') ? *S1 & ~32: *S1; 


b (*s2 >= ’al && *S2 <= '2') ? *S2 & ~32: *S2; 
if (a != b) 
{ 
if (a > b) 
result = 1; 
else 
result = 2; 
break; 
} 
} 
else 


if (*sl > *s2) 
result = 1; 
else 
result = 2; 


break; 
} 
} 


if (result == 0) 


{ 
if (*sl == *s2) 


result = 0; 
else if (*s1) 

result = 1; 
else 

result = 2; 
} 


ea (result); 
The routine first__difference returns the index of the first char- 
acter that differs between two strings. If the strings are equal, the 
routine returns the value —1. 


char *s1="This” 
char *s2="THIS"” first_difference 
int ignore__case=1 


—1 Strings are equal 
Index of first character that differs 
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/*: . 

* first difference (sl, s2, ignore case) 

* : 

* Return the index location of the first character that differs 
x between sl and s2. If the strings are equal, return the value -1. 
, 

* sl (in): string to compare. 

* s2 (in): string to compare. 

x ignore case (in): If 1, ignore case of letters. 

* 

* location = first difference ("TURBO C", “turbo c", 1); 

* : : 

xi, 


int first difference (char *sl, char *s2, int ignore case) 
{ 
int i; 
char a; be 
for (i = 0; *Ssl && *S2; slt+t+, S2++, itt) 
if (*sl !='*s2) | 
{ 
if (ignore case) 
= (*s) >= al 6: sl <s-' 20) 2° *sl. & «325. *S1; 
b = (*s2 >= ‘a! && *s2 <= 'z’) ? *s2 & ~32: *s2; 


else 
break; 
} 


if (*sl || *s2) 
return (i); 
else 
return (-1); 


The routine index returns the starting index of a substring 
within a string. If the substring is not found, the routine returns the 
value —1. | 


char «str="This is” 


Ween index 
char *substring="is 


2 Starting index of is 
— If substring not found 


™ 
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index (substring, string) 


Return the starting index of the substring within a string 
or the value -1 if the substring is not found. 


substring (in): substring to search for. 
String (in): string to examine. 


if (index ("PATH=", *ENV[1]) != -1) 


/ 


int index (char *substr, char *str) 


{ 


in 
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char *substring, *string, *start = str; 


while (*str) 
for (string = str++, substring = substr; 
*string == *substring; stringt+, substring+tt) 
if (! *(substring+1) ) /* end of substring */ 
return (str - start - 1); 


return (-1); /* substring not found */ 
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The function str__count returns a count of the number of occur- 
rences of a substring within a string. If the substring does not occur 


the string, the value 0 is returned. 


char «str "this is” 


char *substring="is” str__count 


2 Number of occurrences 
of is in the string 
0 If substring is not found 


str_count (substring, string) 


Return the number of occurrences of the substring in the er Eatg 
or the value 0 if the substring is not found. 


substring (in): substring to search for. 
String (in): string to examine. 
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* count = str_count ("is", "This is a test"); 
+/ 
int str_count (char *substr, char *str) 
char *substring, *string; 
int count = 0; 


while (*str) 
for (string = str++, substring = substr; 


*string == *substring; string++, substring+tt+) 
if (! *(substring+1) ) /* end of substring */ 
++count; 
return (count); /* substring not found */ 


} 


Conversion Routines 


Periodically a program must convert a string representation of a 
value to its numeric format. Consider the following program: 


main () 


char agestr[5]; 
int age; 


printf ("Enter your age\n"); 

gets (agestr) ; 

if (ascii_to_int (agestr, &age) != -1) 
printf ("%d\n", age); 


else 
printf ("Invalid age entered\n") ; 


~The program invokes the function ascii__to—int, which converts a 
string representation of an integer value to an actual value of type 
int. If the string contains 1233”, the routine returns the integer 
value 1233. However, if the string contains an invalid character 
(such as ”123d3”), the routine returns an error status value. 


char «ascii=”123” 
int «value 


ascii__to__int 


0 
—1 
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—e 123 


Successful 
Invalid character found 


OE eee Dee ce ee at at Eee acne) Tg aes Sun co ig Oy ce aes ig age la a 


/* 

* ascii to_int (str, value) 

* 

* Convert a string representation of a numeric value to the 
* actual integer value. 

* 

* str (in): string containing numeric representation. 

* value (out): actual integer value. 

* 

* if (ascii_to_int ("1112", &value) != -1) 

* 

* If the character contains invalid characters, the value -1 is 
* returned. 

* 

*/ 


ascii to_int (char *str, int *value) 
{ 


int sign = 1; /* -1 if negative value */ 


*value = 0; 

while (*str == ’ ’) /* skip leading blanks */ 
strt+t; 

if (*str == '-' || *str == '+/) 
Sign = (*strt++ == ’-') ? -1: 1; 


while (*str) 
if ((*str >= '0’) && (*str <= ’9%)) 
 *value = (*value * 10) + (*str++ - 48); 
else 
return (-1); /* invalid character */ 


*value *= sign; 


return (0); 
} 


In just the opposite manner, the routine int__to—ascii converts 
an integer value to its string representation. 
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char «ascii : "555" 


int value=555 - i aeen 


& 
. int_to_ascii (value, str) 
: Convert an integer value to its character string representation. 
* str (out): string to contain the numeric representation. 
value (in): integer value to convert. 
s int_to_ascii (str, 22); 
; 


/ 
int_to ascii (int value, char *str) 


{ : 
int sign = value; 


char temp, *savestr = str; 


if (value < Q) 
. value *= -1; 


do 
{ 
*str++ = (value % 10) + 48; 
value = value / 10; 
} 
while (value > 0); 


if (sign < Q) 
Fstrth = =! 5 


*stres ss V0" 3° 


while (savestr < str) 
{ 
temp = *str; 
*str-- = *savestr; 
*savestr++ = temp; 


Admittedly, this has been a fast trip through pointer-manipulation | 
routines. If you do not yet feel comfortable with the concept of a 
pointer, experiment with the previous routines before proceeding. 
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Arrays of Pownters 


Just as C allows you to have an array of characters, it also allows you 
to create an array of pointers. For example, consider the following 
definition: 


char *summer [3]; 


C will create an array indexed from 0 to 2 that contains three point- 
ers to character strings. You can assign values to each string ele- 
ment and then display them, as shown here: 


main () 


{ 


char *summer [3]; 


Int? 

summer [0] = "June"; 
summer [1] = "July"; 
summer [2] = "August"; 


for (i = 0; i < 3; itt) 
printf ("%s\n", summer [i]); 
} 


Using this concept, you can define many useful arrays of point- 
ers to character strings, as shown here: 


char *DAYS[7] = {"Sunday", "Monday", "Tuesday", 
"Wednesday", "Thursday", "Friday", 
"Saturday" }; 


This program uses an array of pointers to display an ASCII, 
decimal, octal, and hexadecimal chart. 


char *ascii[] = ({"NUL", "SOH", "STX", "EXT", "EOT", 
" ENQ we ; "ACK " ; WREL" 7 "BS Ww ; we HT w 
" LF i ; "VT i ; "EE w r w CR w P w SO t j 
"ST an "DLE", "DC1 ae "DC2 " YDS") 
"DC4 bi ; "NAK" 7 t SYN" y "ETB " j t CAN t P 
"EM Sy "SUB", a choy Oar WES ty "GS * 
i RS i ; "US i ' w SPACE w } : 
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main ({) 
Gig | cme 
for (i = 0; i < 33; itt) | | 
printf ("%03d %030 %03x %s\n", i, i, i, ascii[i]); 


for (; i < 128; itt) 
printf ("%03d %030 %03x %$3c\n", i, i, i, i); 


In order to fully exploit the capabilities found in C, you must be 
able to understand and utilize arrays of pointers to character 
strings. 


Command-Line Processing 


Each time you enter a command from the DOS prompt, the 
sequence of characters you enter constitutes a command line, as 
shown here: | | 


A> COPY SOURCE TARGET 


One of the most powerful capabilities of C is that it allows easy 
access to the command line used to invoke the program. In order to 
exploit this access, you must define main within your program, as 
shown here: 


main (int argc, char *xargv[]) 


{ 
} 


These two parameters provide your access to the command line. The 
first, argc, contains the number of command-line arguments. The 
second, argv, is an array of pointers to character strings that contain 
the actual arguments. | 


POINTER MANIPULATION 81 


Before your C program executes, built-in header code (which 
assigns the number of command-line arguments to arge and the 
actual arguments to the elements of the array argv) executes. Once 
this processing is complete, this code invokes main. In the following 
command line, 


A> COPY SOURCE TARGET 


the variable argc will contain the value 3 and the elements of argu 
will point to the following: 


argv[0] points to COPY 


argv[1] points to SOURCE 
argv[{2] points to TARGET 


You can verify this simply by executing the following program, 
which displays each of its command-line parameters: 


main (int argc, char *argv[]) 
int i; 


for (i = 0; i < argc; i++) 
printf ("%s\n", argv[il]); 


The true power of command-line processing is shown when you 
examine the file-manipulation programs later in this text. For now, 
here is a program that displays the contents of the file specified by a 
command-line argument: 


A> SHOW FILENAME .EXT 


#include <stdio.h> 


main (int argc, char *argv[]) 
{ 
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FILE *fopen (), *fp;_ 
char str[(255); 


if (arge > 1) 
if (!(fp = fopen (argv[1], "r"))) 
printf ("Invalid file %s\n", argv[1]); 
else 
{ 
while (fgets (str, 255, fp)) 
printft ("ts", str); 


fclose (fp); 
} 


Accessing Environment Entries 


You may be familiar with the DOS environment, which is a region 
of memory that DOS sets aside to store information. 
For example, issue the DOS set command as follows: 


A> SET | | 


DOS will display the contents of its environment entries: 


COMSPEC=C : \COMMAND . COM 


PATH=C: \DOS;C: \TURBOC 


To place a value in the environment, simply use the SET command 
as shown here: | 


A> SET FILENAME=TEST ; 


To verify that the entry was successful, again issue the SET 
command: 
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A> SET 
COMSPEC=C: \COMMAND .COM 


PATH=C: \DOS;C: \TURBOC 
FILENAME=TEST 


Many programs often require access to the environment entries. 
As such, Turbo C allows you to access the environment in a manner 
similar to the command line. Once again, you must modify your 
definition of main: 


main (int argc, char *argv[], char kenv[]) 


{ 
} 


Just as argv is an array of pointers to the command line, env 1s 
an array of pointers to the environment entries. This program uses 
env to display the current environment. 


main (int argc, char *argv(]J, char *env[]) 
{ 
while (*env) 
printf ("%s\n", *envt+t); 


} 


The following program combines command-line manipulation 
with environment processing to display the value of a specific envir- 
onment entry. 


A> SHOWENV PATH= 


In this case, the program displays the value associated with the 
PATH entry (if it is found): 


main (int argc, char *argv[], char *env[]) 
{ 


void str_to_uppercase(); 


if (argc > 1) 
{ 
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str_to uppercase (argv[1]); 


while (*env) . 
if (index (argv[1], *env) == 0) 
printf ("%s\n", *envt+t); 
else . 
env++; 


Some programmers have difficulty opening files that do not 
reside in a fixed directory or the current directory. The DOS envir- 
onment may provide a solution. Assume that the file you need to 
open is called DATA.DAT.: This file can reside in any DOS subdirec- 
tory. As such, you can simply place an entry in the environment that 
tells you where the file resides: | 


_ The program then uses this information to locate the file in order to 
_ successfully open the file. The program simply searches each envi- 
ronment entry as shown in the previous program. 


Far Pointers 


Each of the pointers used thus far was a 16-bit address. Such point- — 
ers are termed near pointers because they can only be used to access | 
memory locations within the 64KB data segment. Most C programs 
never have access to memory regions beyond this. 

- However, an advanced program periodically has a requirement 
to access memory outside of this region. In such cases, the program 
must use far pointers, which contain 32-bit addresses. Unlike near 
pointers (which can only offset into the current 64KB data segment), 
a far pointer allows you to define a 16-bit segment along with a 16- 
bit offset address (see Figure 3-5). 
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31 16 15 0 


}———— 32-bit address ————__+} 


Figure 3-5. Offset address of far pointer 


Examine the DOS memory map shown in Figure 3-6. Note that 
the computer uses the memory region B800:0000 to address the color 
video display memory. Knowing this, you can use a far pointer to 
reference this memory region. In so doing, you can perform 
memory-mapped output. 

The computer displays characters by placing the ASCII code for 
the character into one of these memory locations, followed imme- 
diately by the character’s display attribute value (color, boldface, 
and so on), as shown in Figure 3-7. As such, you can place the letter 
"A” in the upper left corner of the screen, as shown here: 


main () 


char far *letter = 0xB8000000; 
char far *attr = 0xB8000001; 


*letter = 65; 


kattr = 7; 
} 


DOS Power User’s Guide (Kris Jamsa, Osborne/McGraw-Hill, 
1988) provides several example routines that use far pointers. In 
fact, that book contains a chapter dedicated to memory mapping. in 
most cases, you will use near pointers for your manipulation. How- 
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Interrupt vectors | 
BIOS data area 


OH 


Application 


Transient 
COMMAND.COM 


Reserved for 
future video 
Monochrome 
video 
CGA video 


Figure 3-6. Color video display memory address 


ever, you should understand the functional capabilities of far 
pointers. 
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o A, 
oe oe 
wr PP 


char | attr 80 x 2 (char, attr) 


char | attr char | attr 


-}———_———- 25 rows +4 


Figure 3-7 Displaying a character on screen using ASCII codes and 
display attributes 


Reeursion 


Earlier chapters presented several programs and functions that 
perform their processing by invoking other functions. With Turbo C, 
a function (and even a program) can invoke itself to perform a spe- 
cific task. This is known as recursion. Many advanced programmers 
use recursion to greatly reduce the amount of code in their 
programs. 

In later chapters, you will examine the manipulation of dynamic 
variables to perform specific tasks. Many of the algorithms for those 
programs will be recursive. AS you examine the routines in this 
chapter, you will find that many of them have been previously 
implemented nonrecursively. In most cases you can implement a 
function more efficiently without recursion than with it. (The rea- 
sons for this are presented later in this chapter.) However, because 
many Turbo C programmers make extensive use of recursion in 
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their programs, you should understand the general flow of control 
for recursive functions. 

Take the time to experiment with the routines presented in this 
chapter, and you will find recursion to be a straightforward, power- 
ful, and even enjoyable feature of Turbo C programming. 


Getting Started with Recursion 


The following program invokes the routine show—digit with the 
value 5. The function show_digit in turn uses printf to display the 
value it receives. The routine then invokes itself with the value —1 
(in this case, 4). This process repeats until the value received is equal 
to 0. When invoked, the program displays the following: 


A> SHOWDGT 
5 
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void show digit (digit) 

Recursively display the numbers from digit to zero. 
digit (in): starting number of the digits to display. 
show digit (7); 

is 
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void show digit (int digit) 
{ 


if (digit != 0) 
{ 
printf’ ("sd\n";~ digit); 
show digit (--digit); 
} 
} 


On the first invocation of show—digit, the parameter digit con- 
tains the value 5. The function then displays that value and invokes 
itself with the value 4: 


show—digit (5) 
if (digit !=0) 


printf ("%d\n", 5); 
show—digit (5—1); 
j 


Raa a 


show—digit (4) | 


The second invocation of the function displays the value 4 and then 
invokes itself with the value 3: 
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. show_digit (4) 
if (digit =O) — 
{ 
printf ("%d \n", 4); 
show—digit (4—1); 
| 


show_digit (3) 


This process repeats until the value of digit is 0, as sown in Figure 
4-1. 

Once digit is 0, show—digit no longer invokes itself recursively. 
The last invocation of the function terminates and returns control to 
the previous invocation. | 


show—digit (0) 


show—digit (1) 
if (digit =0) 

{ 

printf ("%d \n", 1); 
show—digit (1—1); 
j 
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show_digit (3) 
if (digit =O) 

{ 

printf ("%d \n",.3); 
show—digit (3—1); 
} 


show__digit (2) 
if (digit !'=0) 

{ 

printf ("%d\n", 2); 
show_digit (2—1); 
j 


show__digit (1) 
if (digit !=0) 

{ 

printf ("%d \n", 1); 
show_digit (1—1); 
} 


show_digit (0) 


Figure 4-1. Processing involved in show_—_digit program (until the 
value of digit rs 0) 
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show—digit (1) 


show.—digit (2) 
if (digit '=0) 
{ 

printf ("%d\n", 2); 
show—digit (2—1); 
} 


This process repeats until no invocation of show—digit is active, as 
shown in Figure 4-2. A recursive function, then, is one that calls 
itself until an ending condition is met. | 

Chapter 2 discussed how Turbo C terminates strings with the 
null character. With this concept in mind, you can write a recursive 
function that determines the number of characters in a string by 
searching for the null character. Given the string “ABC”, the func- 
tion examines the first character. If the current character in the 
string is not the null character, the routine simply adds the value of 
1 to the value returned by the next invocation of the routine string__ 
length. Thus, by using “ABC”, the processing becomes that shown in 
Figure 4-3. | 3 


j 


show_digit (3) 
if (digit !=0) 

{ 

printf ("%d \n", 3); 
show__digit (3-1); 
} 


show_digit (4) 
if (digit !=0) 

{ 

printf ("%d \n", 4); 
show—digit (4-1); 
} 


show_digit (5) 
if (digit !=0) 

{ 

printf ("%d \n", 5): 
show__digit (5-1); 
j 


program is no longer active) 


show__digit (2) 
if (digit !=0) 


printf("%d \n", 2); 
show__digit (2-1); 
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Figure 4-2. Processing involved in show—digit program (until 
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string_length ("ABC") 
if (*s) 
return (1+string__length (++s)); 


string__length ("BC") 
if (*s) 
return (1+string__length (++s)); 


string__length (“C”) 
"if (*s) 
return (1+string__length (++s)); 


string__length (’" ”) 
if (*s) 
return (1+string.length (++s)); 


else 
return (0); 


a Result 


Figure 4-3. Processing involved in string__length program 
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Once it locates the null character, the routine simply works its 
way back through the series of recursive invocations. The following 
routine implements string—length: 


char«s="Turbo C” string—length 


7 Number of characters in the string 


~ 


+ + F + HF HF HH HF HF FF 


string length (s) 

Return the number of characters in the string. 
s (in): string to return the length of. 

count = string_length (string); | 

/ 


int string length (s) 
char *s; 
{ 
return ((*s) ? 1 + string _length (++s): 0); 
} 


Similarly, the routine display—string displays the contents of a 
character string by using recursion. The routine begins by examin- 
ing the current character. If that character is not null, the routine 
displays the character and then invokes itself with the next charac- 
ter. This process repeats until the null character is found. Given the 
string “ABC”, the processing becomes that shown in Figure 4-4. 


as Sa SEE OE POLE IEE 
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display—string (“ABC”) 
if (*s) 


{ 
printf ("%c", 'A’); 
display__string (++s); 
} 


display—string ("BC") 
if (*s) 


printf ("%c",'B’); 
display__string (++s); 
} : 


display__string ("C”) 
if (*s) 
{ 


printf ("%c", ‘C’); 
display__string (++s); 
} . 


display__string (” ”) 


Figure 4-4. Processing involved in display—string program 


In the following case, once the routine locates the null character, 
no further processing is required. The function simply returns con- 


trol to the previous invocation. 
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char *s="Turbo C” display—string Turbo C 


display string (string) 


Display the contents of a character string on the screen display. 


* 
* 
* 
* 
* 
* string (in): character string to display. 
x 
* display string ("This is a test"); 

* 

* 


/ 


display string (char *s) 


if (*s) /* do characters remain? */ 
prantel .("te", *s)-: /* output current character */ 
display string (++s); /* recursively display other characters */ 


By changing the following lines of code, 


DEANEE A" 46", *S)-> 
display string (++s); 


to 


display string (s+1l); 
printf ("%c", *s++); 
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the routine displays the string in reverse order. This is because the 
function first examines the current character in the string. If the 
character is not the null character, the routine invokes itself recur- 
sively with the next character. This process repeats until the routine 
locates the null character. Once the null character is found, the rou- 
tines begin working their way back through the series of invocations 
to display the characters in reverse order, as shown in Figure 4-5. 
The following code implements show_reverse: | 


ELE. 


™~ 


+ + + & HF HF HF HF HF 


show_reverse (string) 


Display the contents of a character string on the screen display 
in reverse order. 


string (in): character string to display. 
show_reverse ("This is a test"); 
/ 


show_reverse (char *s) 


ae 


if (*s) /* do characters remain? */ 
{ | 
show_reverse (s+1); /* recursively show other characters */ 
printf ("%c", *s); /* output current character */- 


} 
} 


Probably the most popular use of recursion is for determining the 
factorial of a value. Table 4-1 illustrates how to calculate the FAC 
rials for the values 1 through 5. The factorial of 5 is 


5 * factorial (4) 
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show_reverse (“ABC”) 
if (*s) 
{ 


show__reverse (s+1); 
printf ("%-c", 'A’); 
} 


show__reverse ("BC") 
if (*s) 
{ 


show_reverse (s+1); 
printf ("%c", 'B’); 
} 


show__reverse ("C”) 
if (*s) 
{ 


show__reverse (s+1); 


printf ("%c", 'C’); 


} 


sShow__reverse (” ”) 


Figure 4-5. Processing involved in show__reverse program 
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Table 4-1. Factorials of Values 1 Through 5 


Value Definition | Result 
1 : 1 | i 
2 1*2 2 
3 1*2%3 6 
4 Lx2aQed 24 
5 L#Qagedah 120 


The factorial of 4 is 
4 * factorial (3) 


This process continues until the factorial of 1 (which, by definition, 
is 1) is reached. For example, to determine the factorial of the value 
3, the processing shown in Figure 4-6 is performed. 

The following routine implements factorial: 


factorial 


6 Result of 3*2*1 


™s 


+  & FF FF FF HF He F 


factorial (value) 

Return the factorial of the value specified. 
value (in): value to return the factorial of. 
fact = factorial (5); 
j 
Seas (int value) 


return ((value <= 1) 2? 1: value * factorial (value-1)); 
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factorial (3) 


if (value > 1) 
return (3 « factorial (3—1)); 


factorial (2) 


if (value > 1) 
return (2 « factorial (2—1));J 


factorial (1) | 


if (value > 1) 

return (value « factorial (value—1)); 
else 

return (1); 


return (2); 


return (6); 


Figure 4-6. Determining the factorial of the value 3 
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Similarly, recursion can be used to compute a Fibonacci number. 
Table 4-2 shows you how to calculate the Fibonacci numbers from 1 
to 5. The following code implements Fibonacci: 


95 ~=6©Value of the tenth Fibonacci number 


fibonacci (value) 

Return the Fibonacci number for the value specified. 

value (in): value to return the Fibonacci number of. 

fibon = fibonacci (10); | 

A Fibonacci number is the sum of the previous two Fibonacci numbers. 


/ 


+ + FH FF HF HH HK KF OF 


fibonacci (int value) 
{ 


return ((value == 1 || value == 2) ? 1: 
fibonacci (value - 1) + fibonacci (value - 2)); 
} 


C is a portable programming language, which means that the code 
that you write on one type of computer in C will likely recompile and 
run on a different type of computer (with little or no modification). 
Portability is one of C’s most important characteristics. However, 
exceptions to the rule always exist. Depending on your target com- 
puter, the number of bits that C uses to represent value of type int 
may differ from 16 to 32 bits. Thus, the range of values that each 
can store may also differ (see Table 4-3). 

In either case, C always uses the most significant (leftmost) bit of 
an integer value as the sign bit, as shown in Figure 4-7. When this 
bit is set (1), the value contained in the lower order bits is considered 
a negative value. When this bit is clear (0), the value is positive. You 
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Table 4-2. Calculation of Fibonacci: Numbers 1 Through 5 


Value Definition Fibonacci Number 
1 1 1 
2 1 1 
3 1+1 Zz 
4 2r1 3 
5 3+2 D 


Table 4-3. Number of Bits Versus Minimum and Maximum Values 


Number of Bits Minimum Value Maximum Value 
16 —32768 32767 
32 2147483648 2147483647 


Data bits Data bits: 


15 14 Y 31 30 0 


Figure 4-7. Example of Turbo C using most significant bit of 
an integer value 
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can use this bit to determine the number of bits Turbo C is using to 
store values of type int. 

If you begin by assigning a value of type int the value 1, you can 
repeatedly shift the value to the left one location until the sign bit 
becomes set. When this occurs, you know the size of the variable (see 
Figure 4-8). 7 


000 0000 0000 0001 | Count = 1 
000 0000 0000 0010 | Count = 2 


000 0000 0000 0100 | Count = 3 


010 0000 0000 0000 | Count = 14 
100 0000 0000 0000 | Count = 15 


1 | 000 0000 0000 0000 } Count = 16° 


Figure 4-8. Shifting a value left one location until sign bit rs set 
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The following code implements word__size: 


word__size 


16 or 32 (depending on your compiler) 


i 


+ + + & * FF FE HF FF 


word count (value) 

Return the number of bits in a value of type int. 
value (in): value to shift left until negative. 
num bits = word count (1); 

/ 


word count (int a) 
{ 
return “(av 0). °2 4 a word count. (a: << 1)-s. 197 


} 


The following routine invokes a recursive implementation of the 
routine fast_copy. Given the string “ABC”, the processing is that 
shown in Figure 4-9. 

The following code implements fast—copy. Note that this routine 
does not perform bounds checking. 


char *s1 = "AAA": Het "AAA" 
char *s2: mat "AAA" 


Warning: fast—copy does not perform bounds checking. 


108 TURBO C PROGRAMMER’S LIBRARY 


fast_.copy (“ABC”, s2) 


if. (s2 = 'A’) 
fast_.copy ("BC”, s2); 


fast_copy ("BC”, s2 ) 


if (s2 = ‘B’) 
fast_copy ("C", s2); 


fast..copy ("C”, s2) 


. if (s2 = 'C’) 
fast_.copy (" ", $2): 


| fast_copy (”" ",s2) 


if (s2="") 
fast_copy("BC”, s2);' 

else 

return; __ 


Figure 4-9. Processing involved in fast_copy program 


+ + + + + + + FF FX FF OF 
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void fast _ copy (source, target) 
Copy the contents of the source string to the target. 


sl (in): source string containing characters to copy. 
Ss2 (out): string receiving characters copied. 


fast copy ("This is a test", stringvar); 


fast copy does not perform bounds checking. 


void fast copy (sl, s2) 


char *sl, *s2; 


{ 
if (*s2 = *s1) 


} 


fast. copy. (+1sl,...44+52)7 
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The following program uses recursion to display the contents of a 
small text file in reverse order. Just as the string-manipulation rou- 
tines presented in Chapter 2 searched a character string one letter 
at a time until the null character was found, the file__reverse rou- 
tine searches for the end of a file. Given the following file, 


the processing becomes that shown in Figure 4-10. 
The following program uses file__reverse to display the contents 
of a file specified by argv[1] in reverse order. 


#include <stdio.h> 


main (int argc, char *argv[]) 


i 
FILE *fp, *fopen(); 
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ace (Ss, 132, fp)) 


file__reverse (fp); 
oe ("AAAA", stdout); 


if (fgets (s, 132, fp)) 


file__ reverse (fp); 
fputs ("BBBB”, stdout); 
} . 


—“AAAA" 


if (fgets (s, 132, fp)) 
{ 


file__reverse (fp); 
fputs ("“CCCC”, stdout); 
} 


if (fgets (s, 132, fp)) 


file__reverse (fp); 


fputs ("“AAAA”, stdout) 


"CCCC" 
"BBBB"” 


Figure 4-10. Processing involved in file_reverse program 
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void file. reverse (FILE *fp); 


if (arge < 2) 
printf ("Invalid usage: FILEREV FILENAME.EXT\n") ; 
else if (! (fp = fopen (argv[{1], "r"))) 
printf ("Could not open $%s\n", argv([1]); 
else 
{ 
file reverse (fp); 
fclose (fp); 
} 


— 


* 
: void file reverse (file pointer) 

: Display the contents of the file specified last line to first line. 
: file pointer (in): pointer to the desired file. 

‘ file reverse (fp); 

* file reverse only works for small files. 

*/ 


void file reverse (FILE *fp) 
{ 
char string[132]; 
if (fgets (string, 132, fp)) 
as | 


file reverse (fp); 
fputs (string, stdout); 


Similarly, the program file—pointer uses recursion to display the 
last ten lines of a file. For example, the command 


A> LAST FILENAME.EXT 


displays the last ten lines of the file FILENAME.EXT, as shown 
here: 


#include <stdio.h> 
main (int argc, char *argv[]) 
A 

FILE *fp, *fopen(); 


char *lines[10], *malloc(); 


int index; 
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int last (FILE *, char *[], int); 


if (arge < 2). 
printf ("Invalid usage: LAST FILENAME.EXT\n") ; 
else if (! (fp = fopen (argv[1], "r"))) 
printf ("Could not open %s\n", argv[1]); 
else 
{ 
/* allocate space for a circular buffer */ 
for (index = 0; index < 10; indextt) 
if (! (lines [index] = malloc (132))) 


printf ("Unable to allocate necessary memory\n"); 
exit (1); 
} 


last (fp, lines, 0); 
fclose (fp); 
} 


id 


/* 

* last (file pointer, lines, index) 

* 

* Display the last 10 lines of the file specified. 
* 

* file pointer (in): pointer to the desired file. 
* lines (in/out): buffer that 10 lines are stored in. 
* index (in): index to the current line. 

* 

* last (fp, lines, 0); 

* 

i 2 


last (FILE *fp, char *lines[], int index) 
{ 


if (fgets (lines[index], 132, fp)) 
last (fp, lines, (index + 1) % 10); 


else 
{ 


Int: 2 


i = (index + 1) % 10; 
while (i != index) 


fputs (lines[i], stdout); 
i= (i + 1) % 10; 
} 

} 


In Turbo C, even the main program is considered to be a func- 
tion. You can invoke main in a recursive manner, as shown here: 
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main (int argc, char *argv[]}) 
{ 
1f (*++argv) 


printf ("%s\n", *argv); 
main (argc, argv); 
} 

} 


In this case, if the program has the following command-line 
parameters, 


A> RECMAIN A BC 


the program displays the first command-line parameter and then 
invokes itself to recursively display the second. This process con- 
tinues until no parameters remain on the command line. | 

By simply changing the code to the following, 


Main (int argc, char *argv[]) 


if (*++argv) 
{ 
main (argc, argv); 
printf ("%s\n", *argv); 
} p 

} 


the program now displays the command-line arguments in reverse 
order. 
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Considerations for Recursive 
Functions 


In many cases, you can reduce the amount of code required to per- 
form a specific task by using recursive functions. 

Essentially, every routine presented thus far could be imple- 
mented recursively. The reasons why you do not do just that are 
speed and space. 

Each time you invoke a Turbo C function, the program must 
place the return address and function parameters into an area of 
memory called the stack, which in turn produces overhead. In most 
cases, the overhead associated with functions is an acceptable trade- 
off in order to achieve increased readability and modularity of code. 
This is not always the case with recursion, however. A recursive — 
function may require many invocations in order to perform a spe- 
cific task. With each invocation comes the overhead of placing the 
return address and variables onto the stack. This overhead can 
make recursive functions quite slow. 

The second concern with recursion is stack space. With each 
invocation of a function, Turbo C places data onto the stack. In most 
cases, the stack can only store 64K of data. Thus, if you have a recur- 
sive function that requires many or large local variables, you can 
quickly use up your allotted stack space. 

During the discussion of dynamic variables in later chapters, you 
will find recursion to be a powerful tool. For now, just concentrate 
on the flow of control for your recursive routines. 


Pipe and I/O 
Redvrection 


By default, each time that you issue a DOS command, the operating 
system obtains its input from the keyboard and displays its output to 
the screen. Thus, the keyboard and screen make up the DOS default 
standard input source and standard output destination (see Figure 
5-1). DOS defines the standard input source as stdin and standard 
output destination as stdout. 

Issue the following command: 


A> DIR 


115 


116 TURBO C PROGRAMMER’S LIBRARY 


[DO (vn ER 


Keyboard DOS 
(stdin) Command stdout 


Figure 5-1. Standard input source and standard output destination 


DOS displays the results of the command to the screen (stdout), as 
shown in Figure 5-2. | 

DOS also provides several I/O redirection operators that allow 
you to redefine stdin and stdout for a program. For example, issue 
the following command: 


| a> DIR > DIR.LST | 


Keyboard DIR 
(stdin) | Command 


stdout 


Figure 5-2. Displaying the results of a command to stdout 
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In this case, rather than displaying the output of the DIR command 
to the screen, DOS has redirected stdout to point to the file DIR. LST, 
as shown in Figure 5-3. 

Turn on your system printer and issue the following command: 


A> DIR > PRN: 


This time DOS redirects the output of the DIR command from the 
screen to the printer, as shown in Figure 5-4. 


(\—-aee2> 
Keyboard . 
(stdin) DOS Monitor 
OQ. 
0 


Write to DIR.LST 


Figure 5-3. Output of DIR to DIR.LST 
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—— 


Keyboard 
(stdin) 


Printer 
(stdout) 


Figure 5-4. I/O redirection from screen to printer 


Use an existing text file on your disk and issue the following 
command: 


A> MORE < FILENAME.EXT 


In this case, DOS leaves stdout unchanged and displays the output of 
the command on the screen. DOS now modifies stdin for the MORE 
command and redirects stdin from the keyboard to the file, as 
shown in Figure 5-5. 

The DOS pipe operator allows you to direct the sutnue of one 
command to become the input of a second command, as shown here: 
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A> DIR | SORT 


In this case, DOS redirects stdout for the DIR command and stdin 
for the SORT command, as shown in Figure 5-6. 

You should note that you can use many of these operators on one 
command line, as shown here: 


A> SORT < FILENAME.EXT | MORE 


Programs that support the DOS input/output (I/O) redirection opera- 
tors are easy to implement with Turbo C. 


MORE Command 


0 


FILENAME.EXT 


Figure 5-5. Redirection of stdin for MORE command 
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IAIUULILUTUL e+] Saal 
Keyboard | 


(stdin) | DOS DIR 


Monitor 


stdin SN 


Keyboard | DOS SORT 


Monitor 
(stdout) 


Figure 5-6. Redirection of stdout for DIR command to stdin for 
SORT command 


Getting Started with I /0 
Redirection 


The first Turbo C program example supports I/O redirection. This 
example program counts the number of lines of redirected input and 
displays the final count following the last line read. For example, if 
your disk contains the following files, 


Volume in drive A is TURBO C 
Directory of A:\ 


155 2-05-88 746a 
1050 6-03-87 :00a 
351 1-26-88 :19a 
498 2-06-88 =0.1 
402 2-05-88 :27p 
1241 2-05-88 :59p. 
543 2-06-88 :44p 
927. 2-06-88 720p 
362 2-06-88 :56p 
9 File(s). 351232 bytes free 


TEST 
MAIN 
SHOW 
TEE 
FACT 
LAST 
TAB 
F2 
MORE 


QARQaANgqgaRAaANaAN 
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the command 


A> DIR | COUNT 


will display 


Line count = 14 


You can also use COUNT to display the number of lines in a file, as 
shown here: 


A> COUNT < FILENAME .EXT 


The following program implements COUNT: 


#include <stdio.h> 
main () 
tae count = 0; 
char line[132]; 


while (fgets (line, 132, stdin) ) 
count++; 


printf ("Line count = %d\n", count); 


The processing required for COUNT is straightforward. The pro- 
gram simply reads data from stdin until the end of the file is found. 
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Next, COUNT displays the count of the number of lines read. | 
Similarly, the program LINENUM places a line number before 
each of the lines it reads from stdin. The command 


A> DIR | LINENUM 


results in 


Volume in drive A is TURBO C 
Directory of A:\ 


155 2-05-88 :46a 

L050 6-03-87 :00a 
ioe 1-26-88 :19a 
498 2-06-88 = CGI 8) 
402 2-05-88 ‘27D 
1241 2-05-88 $5 9p 
543 2-06-88 :44p 
12 F2 927 2-06-88 :20p 
13 MORE 362 2-06-88 2S 6p 
14 9 File(s) 351232 bytes free 


TEST 
MAIN 
SHOW 
TEE 

PACT 
10 LAST 
11 TAB 


dL, 
2 
3 
4 
5 
6 
7 
8 
9 


ARDOGOGG AD 


This following code implements LINENUM: 


#include <stdio.h> 
main () 
int line number = 0; 
char line[132]; 
while (fgets (line, 132, stdin)) 


printf ("td %s", ++line number, line); 
} 


Note that printf writes all of the data to stdout. Thus, you can 
redirect output from LINENUM, as shown here: 
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A> DIR | LINENUM | MORE 


The program STATS combines features from the previous pro- 
grams to display the number of lines, pages, words, and characters 
contained in a file (or redirected input). For example, given the fol- 
lowing file, 


This is a test file. 
Don’t forget about the 


Carriage return and line 
feed at the end of each 
line. 


the command 


A> STATS < FILENAME.EXT 


displays 


Pages = 0 
Lines = 5 
= 20 


Words 
Characters = 100 
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The following program complements STAT.C: 


#include <stdio.h> 
#define lines per page 23 
main () 
ae lines = 0, words = 0, characters = 0; 
int in blanks, i; 
‘char str[132]); 
oe (fgets (str, 132, stdin) ) 


i = 0; /* index into string */ 
in_ blanks = 1; /* assume line starts with blanks */ 


while (str[i]) 
{ 
characters+t+; /* another character */ 
if (str{i]) ==’ ') 


if (! in_blanks) 
{ 


words++; /* blank separates words */ 
in_blanks = 1; /* two blanks in a row is not a word 
} 
} 
else if (str[i] != ’\n’) 


in_blanks = 0; 


else if (! in_blanks) /* word ended at end of line */ 


wordstt; 
i++; 
} 
lines++; /* get the next line */ 


} 


printf ("Pages = %$d\nLines = %d\nWords = %d\nCharacters = %d\n", 
lines / lines_per page, lines, words, characters) ; 
} 


The program FIRST displays the first n lines of the redirected 
input, as shown here: 


A> FIRST 15< FILENAME.EXT 
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In this case, FIRST displays the first 15 lines. If you omit the 
desired number of lines, FIRST displays 10 by default. 


A> DIR | FIRST 


The following code implements FIRST: 


#include <stdio.h> 

main (int argc, char *argv[]) 

Cpe stop line = 10; /* number of lines to display */ 

int count = 0; /* current line number */ 

char line[132]; 

int ascii_to_int (char *, int *); 

if (arge > 1) /* see if user specified a valid number */ 
if (ascii_to_int (argv[1], &stop_line) == -1) 

stop line = 10; 
while (fgets (line, 132, stdin) && (++count <= stop line) ) 


fputs (line, stdout); 
} 


The next program uses the routine LAST (presented in Chapter 
4) to display the last ten lines of redirected input, as shown here: 


A> DIR | LAST 


The following code implements LAST: 


#include <stdio.h> 

main () 
char *lines[10], *malloc(); 
int index; 


/* allocate space for a circular buffer */ 


Re oP ee ee 


Set oes. 
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for (index = 0; index < 10; index+t) 
if (! (lines [index] = malloc (132))) 
{ 


printf ("Unable to allocate necessary memory\n"); 
exit (1); 
} 


last (stdin, lines, 0); 
} 


Once you develop a library of powerful routines, your program 
development becomes much more direct. 

In a manner similar to FIRST, the program TAB combines 
command-line processing with I/O redirection. In this case, you 
specify the number of spaces the output is to be shifted to the right, 
as shown here: 


A> DIR | TAB 5 


If you omit the desired number of spaces, 


A> TAB < FILENAME .EXT 


TAB will use the value 7 by default. Once again, the program is 
built by using routines presented earlier in the book. 


#include <stdio.h> 

main (int argc, char *argv[]) 
ek spaces = 7; /* number of spaces to insert */ 
char line[132]; 


int ascii_to_int (char *, int *); 
int pad_string (char *, int, int); 


if (argc > 1) 7s see if user specified a valid number */ 
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if (ascii_to_int (argv[1], &spaces) == -1) 
spaces = 7; 


while (fgets (line, 132, stdin) ) 
{ 


if (pad_string (line, spaces, sizeof (line)) == 1) 


printf ("%c Line exceeds %d characters\n", 7, sizeof (line)); 
break ; 
} 


fputs (line, stdout); 
} 
! 


The program FINDWORD displays each line of the redirected 
input that contains the word specified by the user: 


A> TYPE STATES.LST | FINDWORD ARIZONA 


In this case, the processing again becomes straightforward. 


#include <stdio.h> 


Main (int argc, char *argv[]) 
{ 
char line[(132]; 


int index (char *, char *); 


if (arge < 2) 
printf ("invalid usage: FINDWORD WORD\n"); 
else 


{ 
while (fgets (line, sizeof(line), stdin) ) 
if (index (argv[1], line) != -1) 
fputs (line, stdout); 


To increase the program’s capabilities, you can support the /C 
and /V qualifiers as follows: 


/C Display a count of the number of occur- 
rences of the specified word 


/V Display lines that do not contain the speci- 
fied word 
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The final program becomes as follows: 


#include <stdio.h> 


main (int argc, char *argv[]) 
{ 
char line[132]; 
int count_only = 0, contain word = 1, i, count = 0; 


int index (char *, char *); 


if (argc < 2) 
printf ("invalid usage: FINDWORD WORD [/C] [/V]\n"); 


else 
{ 
for (i = 1; i < argc; i++) 
if (index ("/C", argv[{i]) != -1) 
{ . 
count_only = 1; 
break; 
for (1 = 1; i < argc; i++) 
if (index ("/v", argv[i]) != -1) 


contain word = 0; 
break; 
} 


while (fgets (line, 132, stdin) ) 
if (index (argv[1], line) != -1) 


if (count_only) 
count++; 

else if (contain word) 
fputs (line, stdout); 

} 


else if (! contain word) 
fputs (line, stdout); 
} 
if (count_only) | 
printf ("%s occurs %d times\n", argv[1], count); 
} 


Just as the program FINDWORD displayed each occurrence of a 
word in redirected input, the program REPLACE replaces each 
occurrence of a word with the second word specified. 


A> REPLACE begin BEGIN TEST.PAS NEW.PAS 
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The following program implements REPLACE: 


#include <stdio.h> 


main (int argc, char *argv[]) 
{ 
char line[132]; 


int location, len; 
FILE *fopen (), *infile, *outfile; 


int remove_substring (char *, char *); 
int insert string (char *, char *, int, int); 
int next str occurrence (char *, char *, int); 


if (arge < 3) 
printf ("invalid usage: REPLACE TARGET NEW _WORD OLDFILE NEWFILE\n"); 


else if (argc == 3) 


infile = stdin; 
outfile = stdout; 
} 


else if (arge == 4) 


if (! (infile = fopen (argv[(3], "r"))) 
{ 
printf ("REPLACE error opening %s\n", argv{3]); 
exit (1); 
} 
outfile = stdout; 
} 


else if (arge == 5) 


if (! (infile = fopen (argv[3], "r"))) 
{ 
printf ("REPLACE error opening %s\n", argv[3]); 
exit (1); 
} 


if (! (outfile = fopen (argv[4], "w"))) 
{ 
printf ("REPLACE error opening %s\n", argv[4]); 
exit (1); 
} 
} 


len = string length (argv[2]); 


while (fgets (line, 132, infile) ) 
{ 


if ((location = index (argv(1], line)) != -1) 
do 
{ 
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remove substring (argv[1], &line[{location]); 
insert string (argv[2], line, location, sizeof(line)); 


while ((location = next_str_occurrence (argv[1], line, locatio 


 fputs (line, outfile); 


The program MORE.C implements the DOS MORE command. 
Each time MORE displays a screenful of information, it pauses and 
waits for you to press the ENTER key to continue. 


Volume in drive A is TURBO C 
Directory of C:\TURBOC 


<DIR> 11-28-87 
<DIR> 11-28-87 
896 6-03-87 

“245 6-03-87 

527 6-03-87 

517 6-03-87 
1345 6-03-87 
1222 6-03-87 
7316 6-03-87 
2648 6-03-87 

991 6-03-87 

2094 6-03-87 
2407 6-03-87 

71517 6-03-87 

2984 6-03-87 

906 6-03-87 

1782 6-03-87 

542 6-03-87 

434 6-03-87 


PROCESS 
SETJMP 
SHARE 
--MORE-- 


H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 
H 


PRP PRP RPP RPP RPP PPPRPHrE RE @wo 


This code implements MORE: 


#include <stdio.h> 
#define lines per page 24 
main () 


{ , : 
int line number = 0; 
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char line[132]; 


while (fgets(line, 132, stdin) ) 
if (++line number % lines _per_ page) 
fputs (line, stdout); 
else 
{ 
fflush (stdout); 
fputs ("--MORE--\n", stdout) ; 
fflush.. (stdout) 
bioskey (0); 
} 


The program TEE allows you to file intermediate results while 
you continue I/O redirection, as shown here: 


A> TYPE FILENAME .EXT | SORT | TEE SORTFILE.EXT | MORE 


This command is illustrated in Figure 5-7. 


SORTFILE.EXT 


Figure 5-7. Processing involved with program TEE 
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By using TEE, you can write results to a file and also to stdout, 
as shown here: 


- #include <stdio.h> 
main (int argc, char *argv[]) 
ae *fopen(), *fp; 
char line[132]; 


if (arge < 2) 
fputs ("invalid usage: TEE FILENAME\n", stdout); 


else 
{ 
if (! (fp = fopen(argv[1], "w"))) 
fputs ("TEE: unable to open output file\n", stdout); 
else . . 


{ 
while (fgets (line, 132, stdin) ) 
{ 


fputs (line, stdout); 
fputs (line, fp); 


} 
fclose (fp); 
} 


Using Standard Error (stderr) 


Periodically your programs will experience an error that results in 
an error message. If you write the following error message to stdout, 


printf ("invalid usage: TEE FILENAME") ; 


the error message will also be redirected. For this reason, you may 
never see the error message. To make sure you see your messages, 
DOS defines an output source called stderr that is guaranteed to 
display error messages to the screen, regardless of redirection. Your 
programs should write all error messages to stderr, as shown here: 


fputs ("invalid usage: TEE FILENAME", stderr); 
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The following program modifies TEE.C to do just that: 


#include <stdio.h> 

main (int argc, char *argv[]}) 
Seis *fopen(), *fp; 
char line[132]; 


if (arge < 2) 
fputs ("invalid usage: TEE FILENAME\n", stderr); 


else 
{ 
if (! (fp = fopen(argv[1], "w"))) 
fputs ("TEE: unable to open output file\n", stderr); 
else 


{ 
while (fgets (line, 132, stdin) ) 
{ 
fputs (line, stdout); 
fputs (line, fp); 
} 
fclose (fp); 
} 
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I/O redirection is a powerful tool. Later chapters discuss how to 
modify many of the programs presented in this chapter so that they 
support I/O redirection and command-line processing. For now, 
experiment with the programs presented in this chapter to increase 


your understanding of I/O redirection. 


DOS Interface 


You are probably familiar with DOS, the operating system for the 
IBM PC and PC compatibles. What you may not know is that a sig- 
nificant portion of DOS is written in C. As is the case with all oper- 
ating systems, the DOS developers were faced with a monumental 
programming task when they wrote DOS. To simplify their task, the 
developers broke it into many small, manageable functions. These 
functions are responsible for operating system tasks such as the 
following: 


¢ File manipulation (open, read, write, close operations) 
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¢ Keyboard input 

e Program startup and termination 

¢ File-creation, file-deletion, and rename operations 
e Memory management (allocate, free, modify) | 

» Disk-drive manipulation 


-e Directory manipulation 


Because DOS must use these services on a continual basis in 


order to operate, each function must remain immediately available _ 


for use. Thus, you can make use of these services from within your 
programs. DOS uses the 8088 registers as its interface to the DOS 
system services. 

Many of these routines appear in the Turbo C run-time library. 
Their names and parameters may differ from the routines pre- 
sented here though the functionality is the same. Use whichever 
implementation best suits your needs, but still study these routines; 
they can teach you a great deal about DOS. 


SOS8S Registers 


The IBM PC and PC compatibles are based on a processor chip 

— called the 8088. Within this chip is a set of storage locations known 
as registers. Since registers are contained within the control process- 
ing unit (CPU) itself, the 8088 can manipulate the values contained 
in the registers quite rapidly. The 8088 has 14 registers, each pe: 
ble of storing 16 bits of data, as the following shows: 
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General-Purpose Registers 


AH AL CH CL 
BH BL DH DL 


Base and Index Registers 


Stack pointer | Source index 
Base pointer Destination index 


Special-Purpose Registers 


ee | a 


Flags register Instruction pointer 


Segment Registers 


Code segment Stack segment 


Data segment Extended segment 
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Your programs communicate to the DOS system services through 
these registers. For example, assume that you want to determine the 
DOS version number that you are using. Place the following value — 
into AH register and invoke the DOS interrupt (INT 21H): 


AH 30H (Get DOS version number) 


On completion, this service places the major and minor versions of 
the operating system into register AX, as shown here: 


AH Contains the minor version number 
AL Contains the major version number 


The following language code fragment invokes the DOS Get Ver- 
sion Number system service: 


MOV AH, 30H 
INT 21H 


INT 21H serves as your means of executing a DOS system service. 


INT 21H 


An wnterrupt is a signal to the CPU from a program or hardware 
device instructing the CPU to suspend temporarily the function that 
it is performing and instead execute a different task. For example, 
each time you simultaneously press the SHIFT and PRINT SCREEN 
keys, DOS temporarily suspends what it is doing in order to print 
the current screen contents. DOS uses INT 21H as its interface to 
the DOS system services. Each time DOS encounters an INT 21H, it 
examines the contents of each of the 8088 registers to determine the 
specific DOS service to perform, along with the required parame- 
ters for the service. In most cases, DOS obtains the service number 
from register AH. | 
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In the previous example, DOS found the value 30H in AH, which 
directed it to perform the Get DOS Version service. In this case, the 
DOS service 02H directs DOS to display the character contained in 
register DL. To invoke this routine, place the corresponding values 
into the 8088 registers and invoke INT 21H, as shown here: 


MOV AH, 2 - ¢ display character service 
MOV DL, 65 ; character to display 
INT 21H ; invoke DOS service 


A goal in developing applications is to write as much of the code 
as possible in a high-level language such as C (as opposed to assem- 
bly language). You must have a means of executing DOS system ser- 
vices from such languages. In the case of Turbo C, a routine called 
intdos provides your interface. To use this routine, you must include 
the file dos.h, as shown here: 


#include <dos.h> 


Remember, the DOS system services use the 8088 registers as 
their interface. The file dos.h contains a structure definition that 
allows your program to emulate the 8088 registers, as shown here: 


struct WORDREGS 
{ 


unsigned int ax, Ds, CX; Ax; Si, -di, cflag;, ‘flags; 


ie 


struct BYTEREGS 
{ 
unsigned char alin ah; bly ph, el; oh; “diy dh; 
}; 


union REGS { 
struct WORDREGS x; 
struct BYTEREGS h; 
}; 


struct SREGS { 
unsigned int es; 
unsigned int Css 
unsigned int SS; 
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unsigned int ds; 


; 
struct REGPACK 
{ 


unsigned r ax, v_bx, r_cx, xr_dx; 
unsigned r_ bp, r_si, r_di, r_ds, r_es, r_ flags; 


° 
lA 


Within your C program you simply assign appropriate values to 
each register (member of the structure). When you later invoke 
intdos, that routine maps the values contained in your structure into 
the appropriate registers, as shown in Figure 6-1. | 

When the DOS system service completes, intdos again maps the 
register values back to your structure, as shown in Figure 6-2. The 
following C program displays the current DOS version: 


#include <dos.h> 
main () 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x30; 
intdos (&inregs, &outregs); 


printf ("DOS Version %d.%d\n", outregs.h.al, outregs.h.ah); 
} | 


DOS System Services — 


The DOS system services are quite powerful. In fact, these services 
make up the toolkit that the DOS developers used to build DOS. By 
using these routines in your programs, you can quickly develop rou- 
tines of professional quality. This section discusses the commonly 
used DOS system services and shows their Turbo C implementa- 
tions. Most of the services are quite straightforward to use and 
many will greatly increase the capabilities of your application. 
Note that many of these routines assume you are using the small 
memory model of the Turbo C compiler. These routines do not pass 
- segment addresses of strings to the intdos routine; instead, they 
simply use the value of the current data segment. Since the small 
memory model is assumed, the routines are successful. If you are 
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=| intcos | = 


regs.flags 


C Structure 


Figure 6-1. Mapping of structure values by wntdos 


using a different memory model, refer to the Osborne/McGraw-Hill 
text DOS Power User’s Guide, by Kris Jamsa Bomserey 1988), for 
specifics on each system service. 

Many of the routines presented in this section are also available 
as run-time library routines under Turbo C. However, because of the 
importance of the DOS system services (along with the tremendous 
capabilities that these services provide), the routines are presented 
for your examination. Experiment with the DOS system services 
and you should find them to be extremely useful. 
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regs.ax 


regs.bx 


regs.cx — = 
regs.dx 
easctieg | \ - 


regs.si 


regs.di | | 


regs.es 


regs.flags 


C Structure 


Figure 6-2. Mapping of register values by indtdos 


ASCII character 
or keyboard scan code 


#1 


~s. 
* 


+ + © * FF FF FE HF FF HF KK OK OF 


DOS INTERFACE 


nclude <dos.h> 


stdin char () 
Get a character from the standard input device. 
character =.stdin char  () ; 


if the uses presses. a special ‘function key, stdin char 
returns the null value on the first invocation. You must 
again invoke stdin char to determine the scan code of the 
special key pressed. This routine echos the character entered 
by the user to the screen. 


/ 


ine stdin char: () 


{ 


} 


union REGS inregs, outregs; 
inregs.h.ah = 0x01; 


intdos (&inregs, &outregs); 
return (outregs.h.al); 


char letter="a"; 


stdout_output 


#include <dos.h> 


void stdout_output (character) 
Write the character specified to the standard output device. 
character (in): character to be written. 


stdout _output (65); 


/ 


143 


144 TURBO C PROGRAMMER’S LIBRARY 


void stdout_output (char character) 
{ 


union REGS inregs, outregs; 


inregs.h.ah 
inregs.h.dl 


0x02; 
character; 


oil 


intdos (&inregs, &outregs) 7 


} 


aux__char 


ASCII character 


#include <dos.h> 


/ * 
* aux char () 
* 
* Get a character from the standard auxiliary device. 
* 
* character = aux char (); 
* : : 
* If a character is not present, aux_char waits until one 
* becomes available. ; 
* 
i 


int aux_char () 
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{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x03; 

intdos (&inregs, s&outregs) ; 
return (outregs.h.al); 

} 


#include <dos.h> 


aA void aux_output (character) ; 

: Write a character to the standard auxiliary device. 

: character (in): character to be written. 

: aux output (65); 

* By default, DOS uses 2400 baud, no parity, 1 stop bit, and 
* 8 data bits. 

*/ 


void aux_output (char character) 


{ 
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union REGS inregs, outregs; 


inregs.h.ah 
inregs.h.dl 


0x04; 
character; 


it fl 


intdos (&inregs, &outregs); 


char letter="a"; stdprn__output 


#include <dos.h> 


‘ void stdprn_output (character) ; 

‘ Write a character to the standard printer device. 
7 Character (in): character to be printed. 

* stdprn output (65); 

+ 

ee stdprn_output (char character) 


union REGS inregs, outregs; 


inregs.h.ah 
inregs.h.dl 


0x05; 
character; 


intdos (&inregs, &outregs) ; 


DOS INTERFACE 147 


char byte=OxFF; 


ASCII character or 
keyboard scan code 


hn ee a Y 
A 
char byte=65 direct_lO 
Ae, 


If byte equals 255 (OxFF), input is performed; 
otherwise, byte is written to the screen 


#include <dos.h> 


fe 

* Girect 10. (byte) 

* 

* Read a character from stdin or write a character to stdout 
* depending upon the value in the variable byte. 

* 

* byte (in): if OxFF, read a character from stdin. If byte’ 
* contains any other value, write it to stdout. 

* 

* direct 10. (65); 

* character = direct_IO (OxFF); 

* 

* 


/ 


int direct_IO (char byte) 
{ 
union REGS inregs, outregs; 


inregs.h.ah 0x06; 
inregs.h.dl byte; 

intdos (&inregs, s&outregs); 
return (outregs.h.al); 
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ASCII character or 
keyboard scan code 


#include <dos.h> 


/* 

* no_echo read () 

* 

* Read a character from stdin without echoing | the character 
* back to the screen display. 

* 

* character = no echo read (); 

* 

* If a character is not present in the keyboard buffer, this 
* routine waits for one to become available. 

* 

* If the user presses a special function key, stdin char 

* returns the null value on the first invocation. You must 
* again invoke stdin_char to determine the scan code of the 
* special key pressed. 

* 

*/ 


int no_echo read () 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x07; 

intdos (&inregs, &outregs) ; 
return (outregs.h.al); 

} 
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EEE 
TEST 
char«string="TEST” string__display 
SEE ETS, 


#include <dos.h> 


™~ 
* 


void string display (string) 


Display the character string specified to the standard 
output device. 


string (out): character string to be displayed. 
string display ("Turbo C Programmer’s Library") ; 


/ 
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void string display (char string[]) 
{ 


union REGS inregs, outregs; 


int. i; 

for (i = 0; string[i]; i++) 

String[i] = ’$'; /* $ indicates last character to display */ 
inregs.h.ah = 9; 

inregs.x.dx = string; 


intdos (&inregs, &outregs) ; 


string[i] = ’\0'; 
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char buffer [255]; 
int size=sizeof (buffer) 


[Ol —epeoars 


buffered__input 


#include <dos.h> 


™~ 
* 


void buffered_input (buffer, size) 


Read characters from the standard input device into a user 
defined buffer. ; 


buffer (in/out): buffer to store characters input. 
Size (in): maximum number of characters that the buffer can store. 


buffered _ input (array, sizeof (array) ); 
The buffer must be defined as follows: 
buffer[0] contains the maximum size of the buffer 


buffer[1] contains the number of characters read 
buffer[2] contains the first character read 


+ &* & & & HF HH HH FF HK HF KF HK HF HF HF SK 


/ 


void buffered_input (char buffer[], int size) 
{ 
union REGS inregs, outregs; 


buffer[(0] = size; /* maximum buffer size */ 
inregs.h.ah = 0xA; 
inregs.x.dx = buffer; /* offset of buffer */ 


intdos (&inregs, &outregs); 
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[] Keyboard check__character__available 


255 if character available 


0 if no character 


#include <dos.h> 


/* 
* check character available () 
* 


* Return the value 255 if a character is currently available in 
* the standard input device, otherwise return the value 0. 


Status = check_character available (); 


/ 


+ + & 


int check_character available () 


{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x0B; 
intdos (&inregs, &outregs); 
return (outregs.h.al); 
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int service; keyboard__service ——<_—— ‘Keyboard 


ASCII character or 
keyboard scan code 


#include <dos.h> 


/* 
* keyboard service (service) 
a 
_* Clear the keyboard buffer and perform the keyboard service 
* specified. 
* 
* service (in): DOS keyboard service to perform. 
x 
* character = keyboard service (7); 
* . 
* By invoking keyboard services in this fashion, you can insure 
* that the type ahead buffer is empty prior to your read operations. 
* 
* 


/ 


int keyboard_service (int service) 


{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x0C; 
inregs.h.al = service; 
intdos (&inregs, &outregs); 
return (outregs.h.al); 
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#include <dos.h> 


void set_drive (drive) 
Set the disk drive to the drive number specified. 


drive (in): Disk drive desired. 


* 

* 

* 

* 

* 

* 

* set_drive (2); 
* 

* Drive numbers are defined as: 
* A= 0, B=1, C=2 

* 
* 


/ 


void set_drive (int drive) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x0E; 
inregs.h.dl = drive; 

intdos (&inregs, s&outregs) ; 
} 
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char buffer [128]; set__disk__transfer__address 


#include <dos.h> 


™~ 
+ 


void set_disk_transfer address (buffer) 

Define a new buffer for the DOS disk transfer area. 
buffer (in): buffer to be used as the DTA. 

set_disk transfer address (char_array) ; 

By default, the DTA points to offset 80H of the PSP. In 
later chapters we will use this region to perform command 


line operations. By modifying the DTA we can prevent DOS 
from overwriting the command line. 


/ 
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void set_disk_transfer_ address (char buffer[]) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x1A; 

inregs.x.dx = buffer; /* minimum 128 bytes */ 
intdos (&inregs, &outregs); 

} 
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int «spc; 4 sectors per cluster 
int «sector__size; disk__information 512 bytes per sector 


int *num__clusters; 1048 clusters per disk 


#include <dos.h> 


7 * 

* void disk_information (spc, sector size, num_clusters) 
* 

* Return the number of sectors per cluster, the sector size, 
* and the number of clusters for the current disk drive. 
* : 

* spc (out): sectors per cluster. 

* sector size (out): bytes per sector. 

* num_cluster (out): clusters per disk. 

x 

* disk_information (&spc, &sector_size, &num_clusters); 
x 

xi 


void disk information (int *spc, int *sector size, int *num_clusters) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x1B; 

intdos (&inregs, &outregs); 

*spc = outregs.h.al; /* sectors per cluster */ 
*sector size = outregs.x.cx; 

*num_clusters = outregs.x.dx; 
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int interrupt__number; 
int segment__address; set__interrupt__vector 


int offset_address; 


#include <dos.h> 


/* | 

* void set_interrupt_vector (interrupt_number, segment, offset) 
" 

* Specify a new interrupt handler routine for a specific interrupt. 
* 

* interrupt_number (in): Interrupt number to modify. 

* segment (in): Segment address of new routine. 

* offset (in): Offset address of new routine. 

* 

* set_interrupt_vector (5, segment_address, offset_address) ; 

* 

* 


/ 


void set_interrupt_vector (int interrupt number, 
int segment, int offset) 
{ 


union REGS inregs, outregs; 


struct SREGS segregs; 


inregs.h.ah = 0x25; 

inregs.h.al = interrupt_number; 
inregs.x.ds = segment; 
inregs.x.dx = offset; 


intdosx (&inregs, &outregs, &segregs) ; 
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int «day; 

int «month; 

int «year; 

int *«day__of__week; 


get_date 


#include <dos.h> 


™ 
* 


void get_date (day, month, year, day of week) 

Return the current system date. 

day (out): day of of the month (1-31) 

month (out): month of the year (1-12) 

year (out): current year (19xx) 

day of week (out): current day of the week (0=Sunday, 6=Saturday) 
get_date (&day, &month, &year, é&day of week); 


/ 
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void get_date (int *day, int *month, int *year, 
int *day of week) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x2A; 
intdos (&inregs, s&outregs); 


*day = outregs.h.dl; 
*day of week = outregs.h.al; 
*month = outregs.h.dh; 

*year = outregs.x.cx; 
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int day=25; | 
int month= 12; — set__date 
int year=1988; 


255 if date is invalid; 0 otherwise 


#include <dos.h> 


/* 
set_date (day, month, year) 


* 

* 

* Set the current system date. 

* 

* day (in): day of of the month (1-31) 

* month (in): month of the year (1-12) 

* year (in): current year (19xx) 

2 

* status = set_date (&day, &month, &year); 

* : 

* If the date specified is invalid, set_date returns the value 255. 
* 
a 

int set date (int day, int month, int year) 


{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x2B; 
inregs.h.dh = month; 
inregs.h.dl = day; 

inregs.x.cx = year; 


intdos (&inregs, s&outregs) ; 


return (outregs.h.al); 
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int «hour; 
int «minute; 


get_time 


int «second; 
int *hundredaths;. 


#include <dos.h> 


* void get_time (hours, minutes, seconds, hundredths) 
* 

* Get the current system time. 

* 

* hours (out): current hour of the day. 

* minutes (out): current minute of the day. 

* seconds (out): current second of the day. 

* hundredths (out): current hundredths of seconds. 

x . 

* get_time (&hours, &minutes, &seconds, éhundredths) ; 
* 
* 


/ 


void get time (int *hours, int *minutes, int *seconds, 
int *hundredths) 
{ 


union REGS inregs, outregs; 
inregs.h.ah = 0x2C; 

intdos (&inregs, &outregs); 
*hours = outregs.h.ch; 
*minutes = outregs.h.cl; 


*hundredths = outregs.h.dl; 
*seconds = outregs.h.dh; 
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int hours=12; 

int minutes=30; 

int seconds=29; 
int hundredths=75; 


set_time 


255 if time is invalid; 0 otherwise 


#include <dos.h> 


[* 
set_time (hours, minutes, seconds, hundredths) 


Set the current system time. 


* 
* 
* 
* 
* hours (out): current hour of the day. 

* minutes (out): current minute of the day. 

* seconds (out): current second of the day. 

* hundredths (out): current hundredths of seconds. 
* 
* 
k 
* 
* 


status = set_time (10, 30, 0, 0); 


If the time specified is invalid, set_time returns the value 255. 
/ 


int set_time (int hours, int minutes, int seconds, 
int hundredths) 
{ 
union REGS inregs, outregs; 
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inregs.h.ah = 0x2D; 
inregs.h.ch = hours; 
inregs.h.cl = minutes; 
inregs.h.dl = hundredths; 
inregs.h.dh = seconds; 


intdos (&inregs, &outregs); 


return (outregs.h.al); 


int «major, DOS__version 


int «minor; 


#include <dos.h> 


void DOS_version (major, minor) 
Return the current DOS version number. 


Major (out): major version number (DOS 3.1 major is 3) 
Minor (out): minor version number (DOS 3.1 minor is 1) 


162 TURBO C PROGRAMMERS LIBRARY 


* 


* DOS version (&major, &minor); 
* 


*/} 


int DOS version (int *major, int *minor) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x30; 

intdos (&inregs, &outregs) ; 
*major = outregs.h.al; 
*minor = outregs.h.ah; 


int exit__status =1; 


| terminate__resident 
int paragraphs=1000;. 


#include <dos.h> 


™ 
* 


void terminate_resident (status, paragraphs) 

Terminate the current program resident in memory. 

Status (in): exit status value for the program. 

paragraphs (in): number of 16 byte paragraphs regions of memory 
required for termination. 


terminate_resident (1, 500); 
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terminate resident (int status, int paragraphs) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x31; 
inregs.h.al = status; 
inregs.x.dx = paragraphs; 


intdos (&inregs, &outregs) ; 


int function=0; 


int «state; ctrl_break__status 


0 CTRL-BREAK checking disabled 
1 CTRL-BREAK checking enabled 


If the value of function is 0, the routine returns current 
state. If function is 1, the routine sets the current state. 


#include <dos.h> 


/* 
* ctrl_break_status (function, state); 
* 
* Get or set the control break status. 
* 
* function (in): if function is 0, return the current Ctrl-Break state 
* if function is 1, set the current Ctrl-Break state 
* state (in): if state is 0, disable Ctrl-Break checking 
* if state is 1, enable Ctrl-Break checking 
* 
* status = ctrl_break_status (0, 0); 
* 
* 


/ 


int ctrl_break_status (int function, int state) 


{ 
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union REGS inregs, outregs; 


inregs.h.ah 


= 0x33; 
inregs.h.al = function; 
inregs.h.dl = state; 


intdos (&inregs, &outregs) ; 


return (outregs.h.dl); 


int « nt: . 16-bit segment address 
pe aeogmelt get_disk__transfer_address 


int «offset; 16-bit offset address 


#include <dos.h> 


~ 
* 


void get_disk_transfer address (segment, offset) 
Return the segment and offset for the DOS disk transfer area. 


segment (out): segment address of the DTA. 
offset (out): offset address of the DTA. 


get_disk_transfer address (&segment, &offset) ; 


By default, the DTA points to offset 80H of the PSP. 
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~ 


DOS INTERFACE 165 


void get_disk transfer address (segment, offset) 
int *segment, *offset; 
{ 
union REGS inregs, outregs; 
Struct SREGS segregs; 


inregs.h.ah = 0x2F; 
intdosx (&inregs, &outregs, &Ssegregs) ; 


*segment = segregs.es; 
*offset = outregs.x.bx; 


int interrupt_number=5; 
int *segment__address; get__interrupt_vector OxOOFE 


int *offset_address; OxFFFF 


#include <dos.h> 


~ 
* 


void get_interrupt_ vector (interrupt_number, segment, offset) 


Return the address of the interrupt handler routine for a 
specific interrupt. 


interrupt _number (in): Interrupt number desired. 
segment (out): Segment address of the routine. 
offset (in): Offset address of the routine. 
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get_interrupt_ vector (5, &segment_address, é&offset_address) ; 
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* 


ees 


void get_interrupt vector (int interrupt_number, 
int *segment, int *offset) 
{ | 
union REGS inregs, outregs; 


struct SREGS segregs; 
inregs.h.ah = 0x35; 
inregs.h.al = interrupt_number; 


intdosx (&inregs, &outregs, &segregs) ; 


*segment = segregs.es; 
*offset = outregs.x.bx; 


int drive=0; — get__free_disk__space 


long int containing - 
free space in bytes 


#include <dos.h> 


™~ 
* 


long get_free disk space (drive) 

Return the number of available bytes for the disk drive specified. 
drive (in): disk drive id desired. | 
disk_drive = get_free disk space (0); 


Disk drives are specified as: 
0 = Current, 1= A, 2=8B,3=C 
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™~ 
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long get_free disk space (int drive) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x36; 
inregs.h.dl = drive; 
intdos (&inregs, &outregs); 


return ((long) outregs.x.ax * (long) outregs.x.bx 
* (long) outregs.x.cx); 


char +«dir=”"\ \TURBO C”; 


make__directory 


DOS error status or 
0 if successful 


#include <dos.h> 


™~ 
* 


make directory (directory) 

Create a DOS subdirectory with the name specified. 
directory (in): name of the subdirectory to create. 
status = make directory ("\\TURBOC") ; 


If make_directory cannot create the directory specified, it will 
return a DOS error status. Otherwise, make directory returns 0. 


/ 
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make directory (char directory[]) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x39; 
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inregs.x.dx = directory; 
intdos (&inregs, &outregs) ; 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 
} 


char «dirm="\\TCOLD”; remove__directory 


DOS error status or 
O if successful 


#include <dos.h> 


™~ 
* 


remove directory (directory) 

Remove the DOS subdirectory with the name specified. 
directory (in): name of the subdirectory to remove. 
status = remove directory ("\\TCOLD") ; 


If remove directory cannot remove the directory specified, it will 
return a DOS error status. Otherwise, remove_directory returns 0. 


/ 
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remove directory (char directory[]) 
{ 


union REGS inregs, outregs; 


Ox3A; 
directory; 


inregs.h.ah 
inregs.x.dx 


DOS INTERFACE 169 


intdos (&inregs, &outregs) ; 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


} 


char «dir="TURBO C’”; change_directory 


DOS error status 
0 if successful 


eee 


#include <dos.h> 


™~N 
+ 


change directory (directory) 

Set the default DOS subdirectory to the directory specified. 
directory (in): name of the subdirectory to select. 

status = change directory ("\\TURBOC") ; 


If change directory cannot select the directory specified, it will 
return a DOS error status. Otherwise, change directory returns 0. 


/ 
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change directory (char directory[]) 


{ 


union REGS inregs, outregs; 


inregs.h.ah 
inregs.x.dx 


0x3B; 
directory; 


intdos (&inregs, &outregs) ; 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


PSEA TAT ES 
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char +*filename=”"CHudson”; 
int attribute=0; 
int «status; 


create__file 
0 If successful 
1 If error 


DOS file handle if status equals 0; 
otherwise, DOS error status 


#include <dos.h> 


/* 

* create file (filename, attribute, status) 

* 

* Create a DOS file with the name specified. Return a file handle 
* associated with the new file. 

* 

* filename (in): name of the file to create. 

* attribute (in): desired file attribute. 

* status (out): -1 if an error occurred, otherwise 0. 

* 

* filehandle = create file ("CHudson"), 0, &status) ; 

* 

* If create file cannot create the file as specified, it returns 
* the error status value. If the creation is successful, create file 
* returns a file handle to the file. 

* 

* 


/ 


create file (char *filename, int attribute, int *status) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x3C; 
inregs.x.cx = attribute; 
inregs.x.dx = filename; 


intdos (&inregs, &outregs); 
*status = (outregs.x.cflag) ? -1: 0; 


return (outregs.x.ax); 


} 
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char «filename=”CHudson”: 


int mode=0; open_file 


int «status; 0 


If successful 
1 If error 


DOS file handle if status equals 0; 
otherwise, DOS error status 


#include <dos.h> 


~~ 
* 


open file (filename, mode, status) 


Open the DOS file with the name specified in the mode given. 
Return a file handle associated with the new file. 


filename (in): name of the file to open. 
mode (in): specifies how the file is to be opened: 

0 is readonly, 1 is write only, 2 is read/write 
status (out): -1 if an error occurred, otherwise 0. 


filehandle = open file ("CHudson", 0, &status) ; 

If open file cannot create the file as specified, it returns 

the DOS error status value. If the open is successful, open file 
returns a file handle to the file. 


/ 
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open file (char *filename, int mode, int *status) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x3D; 
inregs.h.al = mode; 
inregs.x.dx = filename; 


intdos (&inregs, &outregs); 
*status = (outregs.x.cflag) ? -1: 0; 


return (outregs.x.ax); 


} 
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DOS error status or 
0 if successful 


#include <dos.h> 


close file (filehandle) 


Close the DOS file associated with the file handle specified. 


If close file cannot close the file specified, it returns 
the DOS error status value. If the close is successful, 


* 

* 

* 

* 

* filehandle (in): file handle assoicated with the file to close. 
* ; 

* 

* 

* close file returns the value 0. 


close file (int filehandle) 
{ 
union REGS inregs, outregs; 


inregs.h.ah 
inregs.x.bx 


Ox3E; 
filehandle; 


intdos (&inregs, és&outregs); 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 
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int file handle; 
char buffer[255] Data 
int size=sizeof (buffer); 


int «status; O If successful 


read__file 


1 If error 


DOS error status if status equals 1; 
otherwise, the number of bytes read 


#include <dos.h> 


/* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
x 
* 
* 
* 
* 
* 
x 


/ 


read file (filehandle, buffer, numbytes, status) 


Read the number of bytes specfied from a given file into the 
buffer provided. 


filehandle (in): filehandle of the desired file. 

buffer (out): buffer to contain the bytes read. 
numbytes (in): number of bytes to read from the file. 
status (out): error status 1 if error, 0 if successful. 


bytes = read file (filehandle, buffer, 255, &status); 
If an error occurs during the read operation, read file 


returns an error status value. Otherwise, read file 
returns the number of bytes read. 


read file (int filehandle, char *buffer, 


{ 


int numbytes, int *status) 


union REGS inregs, outregs; 
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inregs.h.ah = 0x3F; 
inregs.x.bx = filehandle; 
inregs.x.cx = numbytes; 
inregs.x.dx = buffer; 


intdos (&inregs,. &outregs) ; 


*status = (outregs.x.cflag) ? 1: 0; 


return (outregs.x.ax); 


int file handle; 
char buffer[255]; 


int numbytes=sizeof(buffer); 
int » status; 


write__file 


0 if successful 
-1 If error 


DOS error status 

if the value of status is 1; 
otherwise, the number of 
bytes written 


#include <dos.h> 


™ 
+ 
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write file (filehandle, buffer, numbytes, status) 


Write the number of bytes specfied to a given file from the 
buffer provided. 


filehandle (in): filehandle of the desired file. 
buffer (in): buffer containing the bytes to write. 
numbytes (in): number of bytes to write to the file. 
status (out): error status 1 if error, 0 if successful. 


bytes = write file (filehandle, buffer, 255, &status); 
If an error occurs during the write operation, write file 


returns an error status value. Otherwise, write file 
returns the number of bytes written. 
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write file (int filehandle, char *buffer, int numbytes) 


{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x40; 
inregs.x.bx = filehandle; 
inregs.x.cx = numbytes; 
inregs.x.dx = buffer; 


intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


} 


char «filename="POCKET.OLD”: delete__file 


DOS error status or 0 if successful 


#include <dos.h> 


/* 

* delete file (filename) ; 

* 

* Delete the file with the name specified. 

* 

* filename (in): name of the file to delete. 

* 

* delete file ("POCKET.OLD"); 

* 

* If an error occurs during the delete operation, delete file 
* returns an error status value. Otherwise, delete file 
* returns 0. 

* 

* 


/ 


delete file (char *filename) 
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{ 


union REGS inregs, outregs; 


inregs.h.ah 
inregs.x.dax 


= 0x41; 
= filename; 


intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 
} 


int file handle, 


int directive=0; 
int highoffset=0; 
int lowoffset=255;: 


DOS error status or 0 if successful 


#include <dos.h> 


™~ 
* 


lseek (filehandle, directive, hioffset, looffset) 


Move the file pointer in the file associated with a file 
handle as specified. 


filehandle (in): file handle of desired file. 
directive (in): Specifies how to move the file pointer: 

0 beginning of file, 1 current location, 3 end of file 
hioffset: high order 16 bits of the offset to branch to. 
looffset: low order 16 bits of the offset to branch to. 


lseek (filehandle, 0, 0, 512); 


Offsets are treated as a 32 bit value. As such, we specify 
a high and low 16 bit combination. 


/ 
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lseek (int filehandle, int directive, 
int hioffset, int looffset) 
{ 


union REGS inregs, outregs; 
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inregs.h.ah = 0x42; 
inregs.h.al = directive; 
inregs.x.bx = filehandle; 
inregs.x.cx = hioffset; 
inregs.x.dx = looffset; 


intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


char «filename="TURBO"; |  get__file__attributes 


—1 if error; otherwise, the file’s 
attributes 


#include <dos.h> 


™~™ 
* 


get_file attributes (filename) 
Return the file attributes for the file specified. 
filename (in): file to return the file attributes of. 
attributes = get_file attributes ("Turbo"); 
File attributes include: 

1 readonly 2 hidden 4 system 

8 volume 16 subdirectory 32 archive 


If an error occurs, get_file attributes returns the value -1. 


/ 
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get_file attributes (char *filename) 
{ 


union REGS inregs, outregs; 


inregs.x.ax 
inregs.x.dx 


0x4300; 
filename; 
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intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? -1: outregs.x.ax); 
} 


char «filename ="TURBO"; 
int attribute=1 


set__file__attributes 


—1 If error 
O_ _iIf successful 


#include <dos.h> 


~ 
* 


set_file attributes (filename, attribute) 
Set the file attributes for a file as specified. 


filename (in): file to set the file attributes of. 
attribute (in): desired file attributes. 


Status = set_file attributes ("Turbo", 32); 
File attributes include: 
1 readonly 2 hidden 4 system 
8 volume 16 subdirectory 32 archive 


If an error occurs, set_file attributes returns the value -1. 
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set file attributes (char *filename, int attribute) 
{ 
union REGS inregs, outregs; 


inregs.x.ax = 0x4301; 
inregs.x.cx = attribute; 
inregs.x.dx = filename; 


intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? -1: 0); 


} 


DOS error status or 
0 if successful 


#include <dos.h> 


/* 

* get _directory (directory, drive); 

* 

* Return the current directory for the disk drive specified. 
* 

* directory (out): current directory name. 

* drive (in): disk drive number of the drive of interest. 

* 

* 


status = get_directory (directory, 0); 
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Disk drive numbers are specified as: 
— 0 = Current, 1 = A, 2 =B, 3 =C 


+ + + + 


is 
get_directory (char *directory, int drive) 


union REGS inregs, outregs; 


inregs.h.ah = 0x47; 
inregs.h.dl = drive; 
inregs.x.si = directory; 


intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 
} ( 


char search spec = "*+,+";- | | 

char filename[13]; "ALLOC.H” 
int attribute=0; 

int «hour; 


int «minute; 


find__first 


int «second; 
int «day; 
int «month; 
int «year; 
long «size | 


DOS error status or 
0 If successful 


#1 


™~ 
* 


+ + & © & FE & HF HH HH HF HH HH HF HF FE HH KH HK FF KK KF KF OF 


fi 


DOS INTERFACE 


nclude <dos.h> 


find first (searchspec, filename, attribute, hour, minute, 
second, day, month, year, size) 


Return information on the first file matching the search 
specification given. 


searchspec (in): File name or DOS wildcard characters of the 
files) to match ("A", "TEST <Cc", -'* 4"). 

filename (out): Name of the first matching file. 

attribute (in): Attributes of the files we are searching for. 

hour (out): Hour time stamp. 

Minute (out): Minute time stamp. 

second (out): Second time stamp. 

day (out): Day time stamp. 

month (out): Month time stamp. 

year (out): Year time stamp. 

size (out): File size in bytes. 


status = find first ("*.c", filename, 0, &hour, &minute, 
&second, &day, &month, &year, &size); 


If an error occurs, find first returns the error status value. 
Otherwise, find first returns the value 0. 


/ 

nd first (char *searchspec, char *filename, int attribute, 
int *hour, int *minute, int *second, 
int *day, int *month, int *year, long int *size) 


union REGS inregs, outregs; 


int segment, offset, i; 
unsigned int time, date; 


void get_disk_transfer address (int *, int *); 


inregs.h.ah = 0x4E; 
inregs.x.dx = searchspec; 
inregs.x.cx = attribute; 


intdos (&inregs, &outregs) ; 


if (outregs.x.cflag) 
return (outregs.x.ax); 


get_disk transfer address (&segment, soffset); 


time = peek(segment, offset+22) ; 
date = peek(segment, offset+24); 
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xyear = (date >> 9) + 1980; 
x*month = (date & 0x1E0) >> 5; 
*day = date & Oxl1F; 

xhour = time >> 11; 

*minute = (time & Ox7EQ) >> 5; 
*second = (time & Ox1lF) * 2; 


xsize = peek(segment, offset+28); 
*size = *size << 16; 
x*size += (unsigned) peek(segment, offset+26); 


for (i = 0; i < 13; itt) 
x*filename++ = peekb(segment, offset+30+i); 


x*filename = ’\0’; 


return (0); 


} 


char filename[13]; 


int attribute=0; "ADDC" 
int *hour; 12 

int «minute; 30 

int «second; — find__next 0 

int *day; 25 

int «month; 42 

int «year; 1988 
long «size; 590 


DOS error status or 
O If successful 


#1 


™ 
* 
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fi 


DOS INTERFACE 


nclude <dos.h> 


find next (filename, attribute, hour, minute, 
second, day, month, year, size) 


Return information on the next file matching the search 
specification given on a call to find first. 


filename (out): Name of the first matching file. 

attribute (in): Attributes of the files we are searching for. 
hour (out): Hour time stamp. 

minute (out): Minute time stamp. 

second (out): Second time stamp. 

day (out): Day time stamp. 

month (out): Month time stamp. 

year (out): Year time stamp. 

size (out): File size in bytes. 


status = find next (filename, 0, &hour, &minute, 
&second, &day, &month, &year, &size); 


If an error occurs, find next returns the error status value. 
Otherwise, find_next returns the value 0. 


/ 


nd next (char *filename, int attribute, int *hour, 
int *minute, int *second, int *day, int *month, 
int *year, long int *size) 


union REGS inregs, outregs; 


int segment, offset, i; 
unsigned int time, date; 


void get_disk transfer address (int *, int *); 


inregs.h.ah = 0x4F; 
inregs.x.cx = attribute; 
intdos (&inregs, &outregs) ; 


if (outregs.x.cflag) 
return (outregs.x.ax); 


get_disk transfer address (&segment, é&offset); 


time 


peek (segment, offset+22) ; 
date pe 


ek (segment, offset+24) ; 


*year = (date >> 9) + 1980; 
*month = (date & Ox1lE0) >> 5; 
*day = date & Oxl1F; 
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*hour = time >> 11; 


*minute = (time & 0x7E0) >> oe 
*second = (time & Ox1F) * 2; 
*size peek (segment, offset+28) ; 


*size = *size << 16; 
*size += (unsigned) peek(segment, offset+26) ; 


for (i = 0; i < 13; itt) 
*filenamet++ = peekb(segment, offset+30+i); 


*filename = '\0’; 


return (0); 


“a 


| -_get_disk_verification 


O Verify is off 
1 Verify is on 


#include <dos.h> 


/* 
get_disk_ verification () 


Return the current state of disk verification on (1) or off (0). 
state = get disk verification (); 


/ 
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int get_disk_verification () 
union REGS inregs, outregs; 


inregs.h.ah = 0x54; 
intdos (&inregs, &outregs) ; 
return (outregs.h.al); 


} 


char «source="CONFIG.OLD”; 
char «target="CONFIG.SAV”; 


rename__file 


DOS error status or 0 
if successful 


#include <dos.h> 


/* 

* rename file (source, target) 

* 

* Rename the file specified by source to the name given by target. 
* 

* source (in): old file name. 

* target (in): desired file name. 

* 

* rename file ("CONFIG.OLD", “CONFIG.SAV") ; 

* 

* If an error occurs, rename _file returns the DOS error status code. 
* Otherwise, rename _ file returns the value 0. 

* 

* 
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rename file (char *source, char *target) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x56; 
inregs.x.dx = source; 
inregs.x.di = target; 


intdos (&inregs, &outregs); 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


int file handle; _#_ 


mt «day; —r 12 
int «month; —»~» 1988 
* * 

int *year; get__file__datetime 

int «hour; ‘ 
int «minute: ae 00 
int «second; : 


DOS error status or 
0 if successful 


#include <dos.h> 


™~ 
* 


get_file datetime (filehandle, day, month, year, 
hour, minute, second); 


Return the date and time stamp for the file associated with 
the file handle given. 


filehandle (in): file handle of the desired file. 
day (out): day of month the file was created or modified (1-31). 
month (out): month of year the file was created or modified (1-12). 
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year (out): year file was created or modified (1980-2099). 

hour (out): hour of day file was created or modified (0-23). 
minute (out): minute of day file was created or modified (0-59). 
second (out): second of day file was created or modified (0-59). 


get_file datetime (filehandle, &day, &month, &year, 
&hour, &minute, &second) 


* + + & € F HF F 


/ 


get_file datetime (int filehandle, int *day, int *month, 
int *year, int *hour, int *minute, int *second) 
{ 


union REGS inregs, outregs; 


inregs.x.ax 
inregs.x.bx 


0x5700; 
filehandle; 


intdos (&inregs, &outregs) ; 


*year = (outregs.x.dx >> 9) + 1980; 
*month = (outregs.x.dx & Ox1E0) >> 5; 
*day = outregs.x.dx & OxI1F; 

*hour = outregs.x.cx >> 11; 

*minute = (outregs.x.cx & 0x7EQ) >> 5; 
*second = (outregs.x.dx & Ox1F) * 2; 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


} 


int filehandle; 
int day=25; 
int month=12; 
int year=1988; 
int hour=10; 


set__file__datetime 


int minute=15; ——» 


int second=30; —> 


DOS error status or 0 
if successful 
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#include <dos.h> 


/ 
set_file datetime (filehandle, day, month, year, 
hour, minute, second); 


Set the date and time stamp for the file associated with 
the file handle given. 


filehandle (in): file handle of the desired file. 

day (out): day of month the file was created or modified (1-31). 
month (out): month of year the file was created or modified (1-12). 
year (out): year file was created or modified (1980-2099). 

hour (out): hour of day file was created or modified (0-23). 
Minute (out): minute of day file was created or modified (0-59). 
second (out): second of day file was created or modified (0-59). 


set file datetime (filehandle, 25, 12, 1988, 10, 30, 0); 
; : 
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set_file datetime (int filehandle, int day, int month, 
int. year, int hour, int minute, int second) 
{ 


union REGS inregs, outregs; 


inregs.x.ax 
inregs.x.bx filehandle; 
inregs.x.dx = (year - 1980) << 9; 
-inregs.x.dx += month << 5; 
inregs.x.dx += day; 

inregs.x.cx = hour << 11; 
inregs.x.cx += minute << 5; 
inregs.x.cx += second / 2; 


0x5701; 


intdos (&inregs, &outregs) ; 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


char path=" \\TURBOC \ \"; create__unique__file "\\TURBOC \ \ 
int attribute=0; 12345678” 


DOS error status 
or 0 if successful 
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#include <dos.h> 


™~ 
* 


create unique file (pathname, attribute) 
Create a file with a unique name in the directory specified. 


pathname (in): directory path to place the file in. 
attribute (in): desired attribute for the file. 


status = create unique file (path, attribute); 
Path names may be defined as: 


char path [255] 
char path [255] 


"\ \TURBOC\\OLDFILES\\"; 
i ae 
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/ 


create unique file (char *pathname, int attribute) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 0x5A; 
inregs.x.cx = attribute; 
inregs.x.dx = pathname; 


intdos (&inregs, &outregs) ; 


return ((outregs.x.cflag) ? outregs.x.ax: 0); 


get_program__segment_prefix 


Segment address of PSP 


#include <dos.h> 


/* 
* get_program segment prefix () 
ns 
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* Return the segment address of the program segment prefix for 
* the current program. 
* 


wd 
get_program segment _prefix () 
er REGS inregs, outregs; 
inregs.h.ah = 0x62; 
intdos (&inregs, &outregs); 


return (outregs.x.bx); 
} 


Using the Programs 


Admittedly, this chapter has presented you with a large collection of 
routines. Although many of these routines appeared to perform 
basic functions, they become quite powerful when you use them in 
larger programs. Many of the programs in later chapters make 
extensive use of these routines. 


Turbo C BIOS 
Interface 


Chapter 6 discussed how to use the DOS system services to add 
many powerful routines to your library of Turbo C functions. Just as 
DOS provides a series of routines that your Turbo C programs can 
access, so do the IBM PC and PC compatibles. This collection of 
routines resides in the PC’s read-only memory (ROM) and is com- 
monly called the ROM BIOS. This is because the routines perform 
the Basic Input Output Services (BIOS). 

As was the case in Chapter 6, this chapter does not attempt to 
implement all of the BIOS services; instead, it examines a select 
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group of services that are useful in many Turbo C applications. Most 
of the routines in this chapter deal specifically with video control. 

As with the DOS system services, you must again use the 8088 
registers as your interface to the BIOS services. Thus, you must 
include the file dos.h at the beginning of your programs, as shown 
here: 


#include <dos.h> 


Unlike the DOS services (which used the routines intdos and 
intdosx), the BIOS services use int86. The calling sequence for int86 
is as follows: — 


int86 (interrupt number, é&inregs, &outregs) ; 


DOS services use INT 21H, as discussed in Chapter 6. The BIOS ~ 
services, however, use the following interrupts: 7 


Print screen INT 05H 
Video services INT 10H 
Equipment service INT 11H 
Memory size INT 12H 
Disk services INT 13H 
Port services INT 14H 
AT extended services INT 15H 
Keyboard services INT 16H 
Printer services INT 17H 
ROM BASIC INT 18H 
Reboot service INT 19H 


Time services | INT 1AH 


In addition to the input and output register structures, you must 
specify an interrupt number, as shown here: 


int86@ (0x10, &intregs, &outregs); 


_ As before, many of these routines exist in the Turbo C run-time 
library. To help you better understand how to control your PC, how- 
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ever, the following routines implement a library of ROM BIOS 
routines: 


print__screen 


#include <dos.h> 


/* 
* void print_screen () 
* 


: Print the contents of the current screen display. 
* print screen (); 
*/ 
void print screen () 
ae REGS inregs, outregs; 


int86 (5, &inregs, &outregs) ; 
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#include <dos.h> 


es | 

* void set_video mode (mode) 

* 

* Set the current video display mode. 

* 

* mode (in): Video mode desired. Common modes include: 

x 0 40 x 25 grey t. 40: x25: color 2 80 x 25 grey 
‘3 3 80 x 25 color 4 320 x 200 color . 
* 5 320 x 200 grey 6 640 x 400 graphics 

* 7 85 x 25 text 

* 

* set_video mode (4); 

* 

* 


/ 


void set_video mode (int mode) 
{ 


union REGS inregs, outregs; 


inregs.h.ah 0; 

inregs.h.al mode; 

int86 (0x10, &inregs, &outregs); 
} 


int top=6; 
set__cursor__size 


int bottom=7; 


#include <stdio.h> 
#include <dos.h> 


/* 


void set_cursor size (start, stop) 
Set the current cursor size. 


* 
* 
* 
* 
* start (in): top scan line. 

* stop (in): bottom scan line. 
* 

* 

* 

* 

* 


set cursor size (8, 7); 


For CGA scan lines range from 0 to 7. For monochrome scan 
lines range from 0 to 13. If you make the top scan line larger 
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* than the bottom scan line, the cursor disappears. 
* 


aes 


void set_cursor_ size (int start, int stop) 
{ 
union REGS inregs, outregs; 


inregs.h.ah = 1; 
inregs.h.ch = start; 
inregs.h.cl = stop; 


int86 (0x10, Ginregs, &outregs); 


int page__number=0; 
int row= 10; 
int column=15; 


set__cursor__position. 


#include <dos.h> 


~s 
* 


void set_cursor position (page number, row, column) 


Place the cursor at the row and column given for the video 
display page specified. 


page number (in): Video page number. 
row (in): Desired row number. 

column (in): Desired column number. 
set_cursor position (0, 10, 15); 


/ 


++ + FF HH HF 


_void set_cursor position (int page number, int row, int column) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 2; 
inregs.h.bh = page number; 
inregs.h.dh = row; 
inregs.h.dl = column; 


int86 (0x10, &inregs, s&outregs); 
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int page__number=0; 


10 
int row; | 15 
int column; , get__cursor__position ; 
int top; 
int bottom; 


#include <dos.h> 


~™ 
* 


void get_cursor position (page number, row, column, start, stop) 
Get cursor information for the video page specified. 


page number (in): Page number to return cursor information for. 
row (out): Current cursor row number. 

column (out): Current cursor column number. 

start (out): Top cursor scan line. | 

stop (out): Bottom cursor scan line. 


get_cursor position (0, &row, &column, &start, &stop); 
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/ 


void get_cursor position (int page number, int *row, 
int *column, int *start, int *stop) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 3; 

inregs.h.bh = page number; 

int86 (0x10, &inregs, &outregs); 
*row = outregs.h.dh; 

*column = outregs.h.dl; 

*start = outregs.h.ch; 

*stop = outregs.h.cl; 
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int page=0; set__active__display__page 


#include <dos.h> 


* 

. set_active display page (page) 
* Select the video display page that is visible on the screen. 
: page (in): Desired video display page. 
: set_active display page (3); 
* By writing to a nonactive video display and then selecting 
é the page as active, the video output appears instantaneous. 
x 


/ 


void set_active_ display page (int page) 
{ 


union REGS inregs, outregs; 


inregs.h.ah 5: 
inregs.h.al page; 
int86 (0x10, &inregs, é&outregs) ; 


int numlines=1; 


SEED, 
int attribute=0; 
int top__row= 10; 
| 
int bottom__row=20; aaa 
Co re eee 


int left_column=10; 


int right_.column=70; 
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#include <dos.h> 


™ 
* 


scroll _ up (numlines, attribute, top row, bottom_row, 
left column, right column) 


Scroll the text on a region of the screen up as specified. 


numlines (in): Number of lines to scroll up. 

attribute (in): Attribute of line(s) left blank by the scroll. 
top row (in): Upper row of the region to scroll. 

bottom_row (in): Lower row of the region to scroll. 

left column (in): Left column of the region to scroll. 

right column (in): Right column of the region to scroll. 


Scroll up: (1,0, 10; 207° 104; 50)% 
f- 
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void scroll_up (int numlines, int attribute, int top _ row, 
int bottom_row, int left_column, int right column) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 6; 
inregs.h.al = numlines; 
inregs.h.bh = attribute; 
inregs.h.ch = top row; 
inregs.h.dh = bottom_row; 
inregs.h.cl = left column; 
inregs.h.dl = right column; 


int86 (0x10, &inregs, &outregs); 


int numlines=1; 
int attribute=0: 


int top__row=10; 


scroll__down 
int bottom__row=20; 


int left_column=10; 


int right_column=70; 
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#include <dos.h> 


as 
* scroll _ down (numlines, attribute, top_row, bottom_row, 
= left_column, right _column) 
* 
* Scroll the text on a region of the screen down as specified. 
* 
* numlines (in): Number of lines to scroll down. 
* attribute (in): Attribute of line(s) left blank by the scroll. 
* top_row (in): Upper row of the region to scroll. 
* bottom_row (in): Lower row of the region to scroll. 
* left_column (in): Left column of the region to scroll. 
* right column (in): Right column of the region to scroll.. 
* 
* scroll down (1, 0, 10, 20, 10, 50); 
* 
* 


/ 


void scroll_ down (int numlines, int attribute, int top_row, 
int bottom_row, int left column, int right_column) 
{ 
union REGS inregs, outregs; 


inregs.h.ah ne 
inregs.h.al numlines; 
inregs.h.bh attribute; 
inregs.h.ch = top_row; 


inregs.h.dh 
inregs.h.cl left_column; 
inregs.h.dl = right_column; 
int86 (0x10, &inregs, &outregs) ; 


bottom_row; 


Hou ut wou ul 


int page=0; 
int character=65; 
int attribute=14; 


write__char__and__attr 


int count=1; 
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#include <dos.h> 


{* | | - 

* void write char _and attr (page, character, attribute, count) 
* Write the number of occurrences specified of a given 

* character (and attribute) on the display page provided. 
Z 

* page (in): Video display page to write character to. 

* character (in): ASCII character to display. 

* attribute (in): Video display attribute of character. 

* count (in): Number of times to display character. 

* 

* write char and attr (0, 65, 14, 10); 

* 

* 


/ 


void write char _and attr (int page, int character, 
int attribute, int count) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 9; 
inregs.h.al = character; 
inregs.h.bh = page; 
inregs.h.bl = attribute; 
inregs.x.cx = count; 


int86 (0x10, &inregs, &o0utregs) ;.- 


int palette=0; 
int color=1; 


- set__color__palette 


#include <dos.h> 


™~ 
* 


void set_color palette (palette, color) 
Set the color palette and select a color for graphics. display. 


palette (in): Desired color palette. 
color (in): Desired color from the palette selected. 


set_color palette (0, 1); 
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void set_color_palette (int palette, int color) 


{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x0B; 
inregs.h.bh = palette; 
inregs.h.bl = color; 


int86 (0x10, &inregs, &outregs); 
} 


int row=10; 
int column=10; 
int color=1; 


write__pixel 


#include <dos.h> 


~ 
* 


void write pixel (row, column, color) 


Write a graphics pixel of the color given at the row and column 
location specified. 


row (in): Pixel row position. 
column (in): Pixel column position. 
color (in): Pixel color. 

write pixel (10, 10, 1); 


f 
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void write pixel (int row, int column, int color) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x0C; 
inregs.h.al = color; 
inregs.x.cx = column; 
inregs.h.dl = row; 


int86 (0x10, &inregs, &outregs); 
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int row=10;. 


int column=10; ge =apxe! 


Pixel color 


#include <dos.h> 


™~ 
* 
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read pixel (row, column) 
Return the color of the pixel at the row and column specified. 


row (in): Pixel row position. 
column (in): Pixel column position. 


color = read pixel (10, 10); 
/ 
read_ pixel (int row, int column) 


{ 


union REGS inregs, outregs; 


inregs.h.ah = 0x0D; 
inregs.x.cx = column; 
inregs.h.dl = row; 


int86 (0x10, &inregs, &outregs); 


return (outregs.h.al); 
} 
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TENE EE TREEE, * 

ge es 
int width; 80 
int mode; get_video__mode 3 
int page; 0 


#include <dos.h> 


™~ 
* 


void get_video mode (width, mode, page) 

Return the current video display status. 

width (out): Number of characters per line (40 or 80). 
mode (out): Current video mode. (See set_video mode) 
page (out): Current video display page. 


get_video mode (&width,. &mode, &page) ; 


/ 
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void get _video_ mode (int *width, int *mode, int *page) 
{ 


union REGS inregs, outregs; 


inregs.h.ah = Ox0F; 
int86 (0x10, &inregs, &outregs); 


*width = outregs.h.ah; 
*mode outregs.h.al; 
*page outregs.h.bh; 
} 


il 
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memory_—size 


Kilobytes of memory 


#include <dos.h> 


/ * ; 
* memory size () 
* . 
* Return the number of kilobytes of memory in the system. 
< . 
* num_bytes = memory size (); 
* 
* 


/ 

memory size () 

Naatba REGS inregs, outregs; 
int86 (0x12, &inregs, &outregs) ; 


return (outregs.x.ax) ; 


[][—Keyoars \ 


get__shift__state | 


Keyboard status 
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#include <dos.h> 


/* 
get_shift_ state () 


Return the current keyboard state. 


state = get_shift_state (); 


bit 0 Right shift depressed bit 1 Left shift depressed 
bit 2 Ctrl depressed bit 3 Alt depressed 
bit 4 scroll lock on bit 5 num lock on 


* 

* 

* 

* 

* 

* 

* get_shift_ state returns a byte whose bits define: 
* 

* 

* 

- bit 6 caps lock on bit 7 ins on 
* 

* 


/ 
get_shift state () 
{ 


union REGS inregs, outregs; 


inregs.h.ah = 2; 
int86 (0x16, &inregs, &outregs) ; 


return (outregs.h.al); 
} 


int color=1; set__border__color 


#include <dos.h> 


/* 


* void set_border color (color) 

* 

* Set the current border color for CGA monitors in text mode. 
5 

* 

* 


color (in): Desired color (0 -.15). 
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* set_border color (1); 
x 
te 
void set_border_color (int color) 


union REGS inregs, outregs; 


inregs.h.ah = 0x0B; 
inregs.h.bh = 0; 
inregs.h.bl = color; 


int86 (0x10, &inregs, é&outregs); 


By using the routines provided in this chapter, you can quickly 
produce routines of professional quality. Experiment with these 
_ functions, and your programs should gain tremendous flexibility. 


Turbo C ANSI 
Support 


Chapters 6 and 7 included several routines that provided video and 
I/O support from DOS and the ROM BIOS services. In addition to 
these routines, the Turbo C run-time library provides many useful 
I/O functions. This chapter, which completes your library of screen- 
manipulation routines, examines the ANSI driver provided with 
both MS-DOS and PC DOS. 

The ANSI driver software intercepts data that is sent from the 
keyboard and data that is sent to the video display in search of 
ANSI commands (see Figure 8-1). 
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ANSI ANSI | 
Keybo 


Figure 8-1. Operation of the ANSI driver 


An ANSI command is a series of characters that begin with an 
ASCII 27 (commonly known as an escape character). For example, 
the following ANSI command clears the screen display and places 
the cursor in the upper-left (home) position on the screen: © 


ESC[2J 


The following program uses this escape sequence and printf to clear 
the contents of the screen display (similar to the DOS CLS 
command): 


main () 


{ 
prance <"\0S3i20")7 
eo 


All of the ANSI commands are this easy to use. 
Before you can use the ANSI driver, you must be sure that the 
ANSI driver software is installed on your system. To do so, be sure 
~ that the file ANSI.SYS is on your boot disk by issuing the following 
command: a 


C> DIR ANSI.SYS 


Volume in drive C is §S 


Directory of C:\ 


ANSI SYS 1651 8-01-87 
1 File(s) 1093632 bytes free 
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Next, place the following entry in the CONF IG.SYS file and reboot: 


DEVICE=ANSI.SYS 


Once the system restarts, DOS will have loaded the ANSI driver 


support. 


Table 8-1 summarizes the ANSI commands discussed in this 


chapter. 


Table 8-1. Summary of ANSI Commands 


Function 


Set Cursor 

- Cursor Up 
Cursor Down 
Cursor Forward 
Cursor Back 
Save Cursor 
Restore Cursor 
Clear Screen 
Clear EOL 
Set Graphic 
Set Mode 
Key Change 
Key Define 


ANSI Command 


ESC[#;#H 
ESC[#A 
ESC[#B 
ESC[#C 
ESC[#D 
ESC[s 
ESC[u 
ESC[2J 
ESC[K 
ESC[#;...;#m 
ESC[=#h 
ESC[#;#p 
E:SC[#;#;“text”; 13p 
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~Cursor-Manipulation Routines 


The following routines use the ANSI services to perform cursor 


manipulation. 
Foe no ea) ae oe aN 
int row= 10; | 
set__cursor 
int column=10 
Ae 


void set_cursor (row, column) 


Use the ANSI driver to set the cursor to the row and 
column position specified. 


row (in): Desired row number. 
column (in): Desired column number. 


set_cursor (10, 10); 


/ 
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void set_cursor (int row, int column) 


printf ("\033[%d;%dH", row, column) ; 
} 


int numrows=10; cursor__up 
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cursor _ up (numrows) 


Use the ANSI driver to move the cursor up the number 
of row specified. 


numrows (in): Number of rows to move the cursor. 
cursor up (10); 


If the cursor reaches the top of the screen, the routine 
completes. 


ij 


void cursor_up (int numrows) 


prince ("\033[%dA", numrows) ; 


} 
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/ 


vol 


{ 
} 


int numrows= 10; cursor__down 


cursor down (numrows) 


Use the ANSI driver to move the cursor down the number 


of row specified. 


numrows (in): Number of rows to move the cursor. 
cursor down (5); 


If the cursor reaches the bottom of the screen, the routine 
completes. 


d cursor down (int numrows) 


printf ("\033[%dB", numrows) ; 
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- int numcolumns=25; cursor__forward 


/ * 
* void cursor forward (numcolumns) 
* 
* Use the ANSI driver to move the cursor forward the number 
* of columns specified. 
* 
* numcolumns (in): Number of columns to move cursor forward. 
* . 
* cursor forward (10); 
* * 
* If the cursor reaches the right side of the screen, the 
* routine completes. 
* 
* 


/ 


void cursor forward (int numcolumns) 
{ , 
printf ("\033[(%dC", numcolumns) ; 


int numcolumns=25; cursor__back | 
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/* 

* void cursor back (numcolumns) 

* 

* Use the ANSI driver to move the cursor backward the number 
* of columns specified. 

* 

* numcolumns (in): Number of columns to move cursor backward. 
* 

* cursor backward (10); 

* 

* If the cursor reaches the left side of the screen, the 

* routine completes. 

* 

* / 


void cursor back (int numcolumns) 


{ 
printf ("\033[%dD", numcolumns) ; 


cursor__home 


x 
. void cursor home () 

Use the ANSI driver to place the cursor in the home position. 
* cursor home (); 

*/ 


void cursor home () 


printf ("\033[H"); 
} 
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| Save_cursor [= 


* 
- void save _ cursor () 
* 
* Use the ANSI driver to save the current cursor position for 
* later restoration by restore_cursor. 
* 
A save cursor (); 
* 


/ 


void save _ cursor () 
{ 
printf ("\033[s\n") ; 
} 


restore__cursor | 
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void restore cursor () 


* 

* 

* 

* Use the ANSI driver to restore the cursor position that 
* was saved by a previous call to save _ cursor. 
* 
k 
x 
x 


restore cursor (); 
/ 
void restore cursor () 


printf ("\033[u\n">; 
} 


Erasing 


The following set of routines uses the ANSI commands to erase the 
entire screen display, and to erase the screen display from the cur- 
rent cursor position to the end of the line: 


clear__screen 


/* 
* void clear screen () 
* 
* Use the ANSI driver to clear the current screen contents 
* placing the cursor in the home position. 
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* 
* clear screen: (); 
* 
ef 
void clear screen () 


{ | 
printf ("\033[2d"); 
} 


| clear_col — 


void clear eol () 


Use the ANSI driver to clear the current line from the 
current cursor position. 


Biearieor (); 


/ 
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void clear _eol () 


printt® .("\03s[K™); 
} 


Screen Attributes 


The following routines use the ANSI services to modify the video 
display and the output attributes of data on the screen: 
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set__bold 


void set_bold (command) 
Use the ANSI driver to enable or disable bold text display. 


command (in): If command is 1, bolding is enabled, otherwise 
bolding is disabled. 


set_bold (1); printf ("BOLD TEXT"); 
set bold (0); printf ("NORMAL TEXT"); 


/ 


+ + & HF HF F HF HF HF HF H OK 


void set_bold (int command) 
{ 
printf ("\033[%dm", (command) ? 1: 0); 
} 
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++ + + % FF FF HF FF OF 


void set_blink (command) 
Use the ANSI driver to enable or disable blinking text display. 


command (in): If command is 1, blinking is enabled, otherwise 
blinking is disabled. 


set blink (1); printf ("BLINKING TEXT"); 
set blink (0); printf ("NORMAL TEXT"); 


/ 


void set blink (int command) 


{ 


printf ("\033[%dm", (command) ? 5: 0); 


} 


set__reverse 


* + + + FH F HF HK F HF OF 


void set_reverse (command) 
Use the ANSI driver to enable or disable reverse video text display. 


command (in): If command is 1, reverse video is enabled, otherwise 
reverse video is disabled. 


set_reverse (1); printf ("REVERSED TEXT"); 
set_reverse (0); printf ("NORMAL TEXT") ; 


/ 


void set_reverse (int command) 


{ 


Prince ("\033[Sdm", (command) ? 7: 0); 
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int foreground=34; 


set__colors 
int background=47; 


/* 

* void set colors (foreground, background) 

* 

* Use the ANSI driver to set the foreground and background 
* colors for text display. 

* 

* foreground (in): Desired foreground color: 

* 30 black 31 red 32 green 33 yellow 
3 34 blue 35 magenta 36 cyan 37 white 
* background (in): Desired background color: 

* 40 black 41 red 42 green 43 yellow 
* 44 blue 45 magenta 46 cyan 47 white 
* 

* set_colors (31, 47); 

* 

“sf 


void set_colors (int foreground, int background) 
{ 
if ((foreground >= 30) && (foreground <= 37)) 
if ((background >= 40) && (background >= 47)) 
printf ("\033[%d;%dm", foreground, background) ; 
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void print reverse video (string) 


Use the ANSI driver to print the string specified in reverse 
video. . 


String (in): Character string to display. 
print_reverse video ("TEST STRING") ; 


/ 


* + + &£ HF FF H HF HF 


void print reverse video (char *string) 
{ 
printf ("\033[7m%s\033[0m", string) ; 
} 


Char «str="TEST”; print_blinking 


void print blinking (string) 

Use the ANSI driver to print the string specified blinking. 
String (in): Character string to display. 

print_blinking ("TEST STRING"); 

/ 


+ + + + SF HF F HH HF F 


void print blinking (char *string) 
{ 
printf ("\033[(5m%s\033[0m", string) ; 
} 
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EE ea, 
char «str="BOLD”; print__bold BOLD 
SERRE AT 


* 
. void print_bold (string) 
‘ Use the ANSI driver to print the string specified bold. 
* String (in): Character string to display. 
: print _bold ("TEST STRING") ; 
* 


/ 
void print_bold (char *string) 


printf ("\033(1m%s\033[0m", string); 
} 
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/ * 

* void ansi_set_mode (mode) 

* 

* Use the ANSI driver to select the mode specified. 
* 

* mode (in): Desired video mode: 

as 0 40 x 25 bw 1 40 x 25 color 

x 2 80 x 25 bw 3 80 x 25 color 

s 4 320 x 200 color 5 320 x 200 bw 

= 6 640 x 200 bw 7 wrap at end of line 
* 

* ansi_set_mode (3); 

k 

x/ 


void ansi_set_mode (int mode) 


if ((mode >= 0) && (mode <= 7)) 
printf ("\033[(=%dh", mode); 
} 


_ Keyboard Reassignment 


The routines presented in this section enable you to trap data from 
the keyboard and to replace that data with either a different key- 
stroke or a series of keystrokes. This means that the ANSI driver 
enables you to redefine a DOS function key (such as F10) with a DOS. 
command (such as DIR). Once defined, each time you press the F10 
key from the DOS prompt, DOS will respond with the DIR com- 
mand, as shown here: | 


Co DIR 


Volume in drive C is S$ 
Directory of C:\TURBOC 


<DIR> 11-28-87 
<DIR> 11-28-87 
896 6-03-87 
215 6-03-87 
527 6-03-87 


8 

— 8 

ALLOC 1 
1 
1: 

517 6-03-87 1: 
1 
1 
1 
i 
1 
e 


ASSERT 
BIOS 
CONTIO 
CTYPE 
DIR 
DOS 
ERRNO 
FCNTL 


1345 6-03-87 
1222 6-03-87 
7316 6-03-87 
2648 6-03-87 
991 6-03-87 : 
9 File(s) 1058816 bytes free 


cameo coe 
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int old="A"; change—_key /OL______\\ 
int old="a"; 


Keyboard 


void change key (old, new) 


Use the ANSI driver to redefine the ASCII code associated 
with the key specified. 


old (in): ASCII code of key to redefine. 
new (in): ASCII code of new key. 


change_key (‘A’, ‘'a’); 
i 


+ + + + + FF *F 


void change _ key (int old, int new) 
{ 
printf ("\033[%d;%dp", old, new); 
} 


int scancode=68; 


define__function__key 
char «str="DIR”: 


Keyboard 


void define function_key (scancode, string) 


Use the ANSI driver to associate a character string with 
a DOS function key. 


+ + + HF F:, 
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scancode (in): Scan code of the key to reassign. 
string (in): String to associate with the key. 


* 
* 
* é 
* define function key (68, "DIR"); (68 is F10) 
* 
*/ 
void define function_key (int scancode, char *string) 
- 


printf ("\033[0;%d;\"%s\";13p", scancode, string); 
} 


The ANSI functions are indeed quite powerful and quite conve- 
nient. However, to avoid problems, be sure that the user has installed 
the ANSI driver. If your program uses the ANSI escape sequences 
to perform I/O operations and the ANSI driver is not installed, the 
screen will contain a strange combination of characters. If this 
occurs, be sure the user installs the ANSI driver as previously 
explained. 7 | | 

Since Turbo C provides several powerful routines for controlling 
your output (see Appendix B), you may choose to use the run-time 
library routines in place of the ANSI routines. In either case, if you 
program under DOS, it is important that you understand that the 
ANSI driver capabilities exist. 


C H A P T EK R 


File Manipulation 


Chapter 5 examined many programs that use the DOS pipe and I/O 
redirection operators to perform file and stream manipulation. This 
chapter builds on those programs to enable support for DOS 
command-line processing and I/O redirection, as shown here: 


A> DIR | FIRST 
A> FIRST FILENAME. TXT . 
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In the latter case, many of the programs presented in this chapter 
will also support DOS wildcard characters by using the routines 
find_tirst and find_next, which were presented in Chapter 6. 


A> FIRST *.* . 


By supporting both command-line arguments and DOS IJ/O redi- 
rection, the programs presented in this chapter will provide you 
with maximum flexibility. | 


Understanding find—first — 
and find—neat 


Before examining the text file-manipulation routines presented | 
later in this chapter, you should first understand how wildcard pro- 
cessing is performed. The following program, LS.C, performs a 
DOS directory command. You can invoke the program as follows: 


A> LS . (List all files by default) 


A> LS FILBENAME.EXT (List all C files) 
A> LS *.C 
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The program will display all of the information normally dis- 
played by the DOS DIR command. For example, if your directory 
contains the following, 


Volume in drive A is C FILES 
Directory of A:\ 


APPENDIX 
ALPHA 
ASCIIINT 
AUXCHAR 
AUXWRITE 
ANSITEST 
ASETCUR 


2688 11-04-87 :55a 
320 2-15-88. - 6258p 
562 2-15-88 2588p 

—- 446 2-15-88 :58p 
596 2=15=68 eosye) 

50 2-15-88 -58p 
431 2-15-88 <58p 
7 File(s) 353280 bytes free 


QAQAaARaANINIAN 


the command 


Ps 


will display the following: 


APPENDIX.C 11/04/1987 
ALPHA.C 02/15/1988 
ASCIIINT.C 02/15/1988 


AUXCHAR.C 02/15/1988 
AUXWRITE.C 02/15/1988 
ANSITEST.C 02/15/1988 
ASETCUR.C 02/15/1988 


The program begins by passing either the contents of argv[1] or 
the character string ** to the routine find—first. If find—first 
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locates a matching file, the program displays the related data. Oth- 
erwise, the program terminates. 

If find__first successfully locates a file, the program invokes the 
routine find—next to locate the next file matching the original 
search specification. If a new file is found, the program displays the 
file information, and this process repeats. Otherwise, the program 
terminates. The following code implements LS: 


main (argc, argv) 
int argc; 
char *argv[]; 
{ 
int day, month, year, hour, minute, second, status; 
long size; 
char filename[13]; 


int find_first (char *, char *, int, int *, int *, int * 
int *, int *, int *, long int *); 
int find_next (char *, int, int *, int *, int *, 
int *, int *, int *, long int *); 
if (argc < 2) 
Status = find first ("*.*", filename, 0, &hour, &minute, 
&second, &day, &month, &year, &sSize); 
else . 
Status = find first (argv[1], filename, 0, &hour, é&minute, 
&second, &day, é&month, &year, &size); 


while (status == 0) 
printf ("%-15s %02d/%02d/%d\t%02d:%02da:%02d %91d bytes\n", 
filename, month, day, year, hour, minute, second, size); 


Status = find _next (filename, 0, &hour, &minute, &second, 
&day, &month, &year, &size); 
} 


} 


The program ATTR.C enhances the DOS ATTRIB command, 
which sets or displays a file’s attributes. This program supports the 
attributes shown in Table 9-1. 
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Table 9-1. Attributes Supported by ATTR.C Program 


Attribute Meaning 


Normal 
Read-only 
Hidden 
System 
Volume label 
Subdirectory 
Archive 


ho o> CO Pm NW RH © 


CS 


Inveke the ATTR.C program as follows: 


A> ATTR *.* (Display file attributes) 
A> ATTR 1 *.C (Set C files to read-only) 


A> ATTR 0 *.* (Set files to normal attributes) 


If you use ATTR to set a file to read-only and later try to delete or 
modify the file, DOS will display the following: 
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Access Denied 


The following code implements ATTR.C: 


main (argc, argv) 
int argc; 
char *argv[]; 
t 
int status, attributes, day, month, year, hour, minute, second; 
long size; 
char filename[13]; 


if (argc == 1) 
{ 
printf ("ATTR invalid usage: ATTR [attribuice] FILESPEC\n") ; 
exit (1); 
} 
else if (argc == 2) 


status = find first (argv[1], filename, 0, &hour, &minute, &second, 
&day, &month, &year, &Size); 
else 
{ 
if (ascii _to_ int (argv[{1], &attributes) == -1) 
{ 
printf ("ATTR invalid attribute %s\n", argv[{1]); 


OxiG. t2)3 
} 
status = find _first (argv[2], filename, 0, &hour, &minute, &second, 
: &day, &month, &year, &Size); 
} 
while (status == 0) 


if (argc == 2) 
printf ("%-15s d\n", filename, get file attributes (filename)); 
else if (set_file attributes (filename, attributes) == -1) 
printf ("ATTR Error modifying %s\n", filename); 
Status = find next (filename, 0, &hour, &minute, &second, 
&day, &month, &year, &Size); 


_ The program STAMP.C allows you to set a date and time stamp 
for a file (or files) to the current system date. Invoke the program as 
follows: 
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A> STAMP FILENAME .EXT 


A> STAMP *.C 
A> STAMP *,.* 


The following code implements STAMP.C: 


main (argc, argv) 
int argc; 
char *argv[]; 
{ 
int file, status, fday, fmonth, fyear, fhour, fminute, fsecond; 
int sys dow, sys day, sys _ month, sys year, sys hour, 
Sys _ minute, sys second, sys_hundredths; 


long int size; 
char filename[13]; 


if (arge < 2) 
{ 
printf ("STAMP invalid usage: STAMP FILESPEC\n") ; 
exit (1); 
} 


Status = find first (argv[1], filename, 0, &fday, &fmonth, 
é&fyear, &fhour, &fminute, &fsecond, &size); 


get_time (&sys_hour, &sys minute, &sys_second, &sys_ hundredths) ; 
get_date (&sys day, &sys month, &sys year, &sys dow); 


while (status == 0) 
{ 
file = open file (filename, 1, &status); 
if (status == -1) 
printf ("STAMP error modifying %s\n", filename); 


status = set _file datetime (file, sys day, sys_month, sys year, 
sys hour, sys minute, sys _ second); 
if (status == -1) 
printf ("STAMP error modifying %s\n", filename) ; 
close (file); 


Status = find_next (filename, 0, &fday, &fmonth, é&fyear, 
&fhour, &fminute, &fsecond, &size); 


The routines find_first and find__next add tremendous flexibil- 
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ity to your programs. Each of these routines will be used extensively 
throughout this chapter. 


File-Manipulation Routines 


The following utility programs deal exclusively with file manipula- 
tion that is based on command-line arguments. The first program, 
DISPLAY.C, enhances the functional capabilities of the DOS TYPE 
command by supporting wildcard characters and multiple command- 
line arguments, as shown here: 


A> DISPLAY *.* 


A> DISPLAY TEST.C TEST.H DISPLAY.C 


The following code implements DISPLAY.C: 


main (int argc, char kargv[]) 


int i, status, day, month, year, hour, minute, second; 
long size; | . 
char filename[13], buffer[132]; 


FILE *fopen (), *fp; 


int find. first (char *, char *, int; int *, int *; int. *, 
int. *, int *; ant. *, Long -1nt -*); 
int find Next. tchar *; int} ant: *, int-*;, ant *, 
7 “dnt, %,- int. -*). int *, dong int. *); 


i= 1; 
if (arge == 1) 
. prince ("DISPLAY invalid usage: DISPLAY FILESPEC aad Ny 
else 
do { 


status = find first (argv[it++], filename, 0, &hour, &minute, 
&second, &day, &month, &year, &S81ze); 


while (status == 0) 
{ 


if (! (fp = fopen (filename, “"r"))) 
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printf ("DISPLAY error opening %s\n", filename) ; 
else 
while (fgets (buffer, sizeof(buffer), fp) ) 
fputs (buffer, stdout); 


fclose (fp); 


status = find next (filename, 0, &day, &month, &year, 
&hour, &minute, &second, &size); 
} 
} 


while (i < argc); 
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The program FILECOPY uses the DOS low-level file-manipula- 
tion routines presented in Chapter 6 to copy the contents of the first 


file specified to the second, as shown here: 


A> FILECOPY SOURCE.EXT TARGET .EXT 


The program does not support DOS wildcard characters. The fol- 


lowing code implements FILECOPY.C: 


main (int argc, char *argv[)) 
int source file, target _file, status, num_bytes; 
char buffer[255]; 


int open _file (char *, int, int *); 

int create file (char *, int, int *); 

int read file (int, char *, int, int *); 
int write file (int, char *, int, int *); 
int close file (int); 


if (argc < 3) 
{ 


printf ("FILECOPY invalid usage: FILECOPY SOURCE TARGET\n") ; 


exit (1); 
else 

{ 

source file = open _file (argv[1], 0, &status); 

if (status == -1) 
{ 
printf ("FILECOPY error opening %s\n", argv[1]); 
exit (1); 
} 
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} 


target file = create _ file (argv[2], 0, &status); 
if (status == -1) 
{ 
printf ("FILECOPY error opening %s\n", argv[2]); 
exit (1)-% 
} 


while (num_bytes = read _ file (source file, buffer, 
sizeof (buffer), &status) ) 

{ 

if (status => =1) 
{ . 
printf ("FILECOPY error reading %s\n", argv[1]); 
exit (1); 
} 


write file (target file, buffer, num_bytes, &status); 
if (status == -1) 


printf ("FILECOPY error writing %s\n", argv[1]); 
exit (1); 
} 


close file (source file); 
close file (target_file); 


Utility Programs 


The following programs help complete your nay of DOS file- 
manipulation routines. Each program presented in this section sup- 
ports both command-line arguments and DOS I/O redirection. As 
such, these programs maximize your command-line flexibility. 

The first program, MORE.C, modifies the program presented in 
Chapter 5 to support command- line processing and 1/0 redirection, 
as shown herv: 


A> MORE FILENAME. EXT 


A> MORE *.* 
A> DIR | MORE 
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The program begins by examining its command-line parameters. If 
none are present, MORE assumes that its input is redirected I/O, as 
shown here: 


| A> DIR | MORE | 


If the user has instead specified a file, 


A> MORE FILENAME. EXT 


MORE uses the specified file. The following code implements 
MORE.C: 


#include <stdio.h> 
#define lines per page 24 
main (int argc, char *argv[]) 
FILE *file, *fopen(); 
int status, i = 1; 
int hour, minute, second, day, month, year; 
long int size; 
char filename[13]; 
void show file (FILE *); 
in’ find first. (char .*) char *; ant; ant. 4% ant *). ant, 
ine. %, ante ee. int; Tong int... +) 3 
t 


imt. find next (char *, int, @nt:*; int *, int > 
inte Fy. 2h “int: *; Long-antk *) 4 


if (arge == 1) 
show_file (stdin); 
else 
do { 
Status = find first (argv[i], filename, 0, &hour, &minute, 


&second, &day, &month, &year, &size); 
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while (status == 0) 
{ 
if (! (file = fopen (filename, "r"))) 
printf ("MORE error opening %s\n", filename) ; 
else 
show_file (file); 
fclose (file); 
Status = find next (filename, 0, &hour, &minute, 
| ~ &second, &day, &month, &year, &size); 
} 


} 
while (++i < argc); 


void show file (FILE *file) 
{ 
char line[132]; 


int line number = 0; 


while (fgets(line, sizeof(line), file) ) 
if (++line_ number % lines per page) 
fputs (line, stdout); 
else 


{ 
fflush (stdout); 
fputs ("--MORE--\n", stdout); 
fflush (stdout) ; 
bioskey (0); 
} 


In a similar manner, the program LAST.C displays the last ten 
lines of a file or redirected input, as shown here: 


A> LAST FILENAME.EXT 


A> TYPE FILENAME.EXT | LAST 
A> LAST *,* 


The following code implements LAST.C: 


#include <stdio.h> 


main (argc, argv) 
int argc; 
char *argv[]; 
{ 
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FILE *file, *fopen(); 

int i= 1, status, index, hour, minute, second, day, month, year; 
long int size; 

char *lines[({10], filename[13], *malloc(); 


int last (FILE *, char *[], int); 

int find: Tirst- (char *,: char *, (ints ant +, int. *); (Tne. *, 
nt *). ant. *p ant. *)- dong “i1nt: *).4 

int. find next (char *,; int; int *,; jAnt. *) aonb. *, 
Int *). int. “*; ant. *, Long ant. *).3 


/* allocate space for a circular buffer */ 
for (index = 0; index < 10; index++) 
if (! (lines [index] = malloc (132))) 
{ 
printf ("Unable to allocate necessary memory\n") ; 
“@xit. (1L)s 
} 
else 
*lines[index] = ’\0’; 


if (arge == 1) 
last (stdin, lines; \0): 
else 
{ 
do { 
status = find first (argv[{i], filename, 0, &hour, &minute, 
&second, &day, &month, &year, &size); 
if (status != 0) 
printf ("LAST file not found\n"); 


while (status == 0) 

{ 
if (! (file = fopen (filename, "r"))) 

printf ("LAST error opening %s\n", filename); 
else 

last (file, lines, 0); 
fclose (file); 
status = find next (filename, 0, &hour, &minute, 
&second, &day, &month, &year, &size); 

} 


while (++i < argc); 


} 
} 
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In the opposite manner, the program FIRST.C displays the first 


m lines of a file or redirected input, as shown here: 


A> FIRST 100 FILENAME.EXT 


A> FIRST *2* 
A> TYPE FILENAME.EXT | FIRST 
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The following code implements FIRST.C: 


#include <stdio.h> 


main (int argc, char *argv[]}) 


II 


int stop line 10; /* number of lines to display */ 


int i= 2, done = 0, status, index, hour, minute, second, 
day, month, year; 


long int size; 

char filename[13]; 

FILE *fopen(), *file; 

void first (FILE *, int); 

int. find first. (char *, char *, int, int *,; int *, int *, 
ant. 4) “aint-*,. ant. *; long int *) ; 

int find next (char *, int, int *, int *,- int *, 
Int: *) int *y. int *;~ Long “int. *) 

int ascii_to_int (char *, int *); 


if (arge == 1) 
{ 


first (stdin, stop line); /* user entered FIRST */ 
done = 1; 
} 
else if (argc == 2) /* FIRST value or FIRST file */ 
{ 
if (ascii_to_int (argv{1], &stop_line) == -1) 
{ 
stop line = 10; 
i= 1; 
} 
else 


{ 
first (stdin, stop_line); 
done = 1; 
} 
} 7 


else if (argc > 2) /* FIRST value file or FIRST file file */ 
: 
if (ascii_to int (argv[1], &stop line) == -1) 
{ 
stop line = 10; 
4 Aes 13 
} F 
} 
if (! done) 
do { 


status = find first (argv[i], filename, 0, &hour, é&minute, 
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&second, &day, &month, &year, &size); 


if (status != 0) 
printf ("FIRST file not found\n"); 
while (status == 0) 
{ 
if (! (file = fopen (filename, "r"))) 
printf ("FIRST error opening %s\n", filename) ; 
else 


first (file, stop line); 
fclose (file); 
Status = find next (filename, 0, &hour, &minute, 
&second, &day, &month, &year, &Ssize); 
} 


while (++i < argc); 


void first (file, stop line) 
FILE *file; 
int stop line; 
{ 


int: -count. = Os /* current line number */ 
char line[132]; 


while (fgets (line, sizeof(line), file) && (++count <= stop line)) 
fputs (line, stdout); 
} 


The program FINDSTR.C displays each occurrence of a speci- 
fied string either in a file (or files) or in redirected input, as shown 
here: 


A> FINDSTR ARIZONA STATES.LST 


A> FINDSTR- DOS. #2 
A> TYPE TEST.PAS | FINDSTR begin 


The program REPLACE.C replaces each occurrence of a word 
with a second word in either a file or redirected input, as shown 
here: 
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A> REPLACE BEGIN begin TEST.PAS NEWFILE.EXT 


A> TYPE TEST.PAS | REPLACE BEGIN begin 


Note that RE PLACE does not perform wildcard processing. The fol- 
lowing code implements REPLACE.C: 


#include <stdio.h> 
main (int argc, char *argv(]) 
char line[132]; 
int location, len; 
FILE *fopen (), *infile, *outfile; 


int remove_substring (char *, char *); 
int insert string (char *, char *, int, int); 
int next_str_occurrence (char *, char *, int); 


if (arge < 3) 
printf ("invalid usage: REPLACE TARGET NEW_WORD OLDFILE NEWFILE\n") ; 


else if (argc == 3) 
{ : 

infile = stdin; 
outfile = stdout; 
} 


else if (arge == 4) 


if (! (infile = fopen (argv[3], "r"))) 
{ 
printf ("REPLACE error opening %s\n", argv[(3]); 
exit (1); 
} 
outfile = stdout; 
} 


else if (argc == 5) 


if (! (infile = fopen (argv[3], "r"))) 
{ ; 
printf ("REPLACE error opening %s\n", argv[3]); 
exit (1); 
} 


if (! (outfile = fopen (argv[4], "w"))) 
{ 
printf ("REPLACE error opening %s\n", argv[4]); 
exit (1); 
} 
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} 
len = string_length (argv[2]); 


while (fgets (line, 132, infile) ) 
{ 


if ((location = index (argv{1], line)) != -1) 
do 
{ 
remove_substring (argv{1], &line[location]); 
insert string (argv(2], line, location, sizeof (line) ); 


} 
while ((location = next_str_occurrence (argv[1], line, 
location + len)) != -1); 


fputs (line, outfile); 


The program TAB.C enables you to precede lines of a file or 
redirected input, as shown here: 


A> TAB FILENAME.EXT NEWFILE.EXT 


A> TAB 25 FILENAME.EXT NEWFILE.EXT 
A> DIR | TAB 7 


The following code implements TAB.C: 


#include <stdio.h> 
main (int argc, char *argv[]) 
FILE *fopen (), *infile, *outfile; 
int spaces = 7; /* number of spaces to insert */ 
int i = 2; 
char line[132]; 


int ascii_to_int (char *, int *); 
int pad_string (char *, int, int); 


infile = stdin; 
outfile = stdout; 


if (arge > 1) /* see if user specified a valid number */ 
{ 
if (ascii_to_int (argv[1], &spaces) == -1) 


spaces = 7; 
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if (*argv{[i]) 
if (! (infile = fopen (argv[i], "r"))) 
{ 
printf ("TAB error opening %s\n", argv[i]); 
exit (1); . 
} 


if (*argv[i] && *argv[it1]) . . 
if (! (outfile = fopen (argv[it1], "w"))) 
f | 
printf ("TAB error opening %s\n", argv[itl1]); 
exit (1); 
} 
} 


while (fgets (line, 132, infile)) 
if (pad string (line, spaces, sizeof (line)) == 1) 


printf ("%c Line exceeds %d characters\n", 7, sizeof (line)); 
break ; 


} 


fputs (line, outfile); 


The programs EXTRACT.C and REMOVE.C enable you to 
select or remove various portions of a file or redirected input. The 
first, EXTRACT.C, writes selected lines of a file (or redirected 

input) to a second file or to the screen, as follows: 


A> EXTRACT 0 50 TEST.C TEST.NEW 
A> DIR | EXTRACT 0 25 


Assuming that the file C.DAT contains the following, 
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WOMAN OBWNHE 


the command 


| A> EXTRACT 3 5 C.DAT 


will display the following: 


The following code implements EXTRACT.C: 


#include <stdio.h> 


main (int argc, char *argv[]) 
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FILE *fopen (), *infile, *outfile; 
int start_line, stop_line, count; 
char line[132]; | 
int ascii _to_int (char *, int *); 
infile = stdin; 
outfile = stdout; 
if (argc < 3) 
printf ("EXTRACT invalid usage: EXTRACT # # FILE FILE\n"); 


exit (1); 
y 


if (ascii_to_int (argv[1], &start _iine) == -1) 
printf ("EXTRACT invalid start Tine td\n", arava ie 


if (ascii_to_ int (argv{[2], &stop line) == -1) 
printf ("EXTRACT invalid stop line %d\n", argv[2]); 


if (argc >= 4) 
if (! (infile = fopen (argv[3], "r"))) 
{ : 


printf ("EXTRACT error opening %s\n", argv[3]); 
exit (1); 
} 


if (argc == 5) . 
if (! (outfile = fopen (argv[4], "w"))) 
{ 
printf ("EXTRACT error opening %s\n", argv[4]); 
exit (13-3 


for (count = 1; fgets (line, sizeof(line), infile); count+t++t) 
{ 
if (count >= start_line) 
fputs (line, outfile) ; 


if (count == stop line) 
break ; 


In a similar manner, the program REMOVE.C deletes lines 
from a file (or redirected input) and writes the result to the screen 
or to a second file, as shown here: 


A> REMOVE 0 10 FILENAME.EXT NEWFILE.EXT 


A> TYPE FILENAME.EXT | REMOVE 0 10 NEWFILE.EXT 
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Given the file C.DAT, the command 


A> REMOVE 3 5 C.DAT 


will display the following: 


The following code implements REMOVE.C: 


#include <stdio.h> 
Main (int argc, char *argv[)]) 
ie *fopen (), *infile, *outfile; 
int start_line, stop line, count; 
char line[132]; 
int ascii_to_ int (char *, int *); 
infile = stdin; 
outfile = stdout; 
if (arge < 3) 
printf ("REMOVE invalid usage: REMOVE # # FILE FILE\n"); 
exit (1); 
if (ascii_to_ int (argv[1], &start_line) == -1) 
printf ("REMOVE invalid start line %d\n", argv[1]); 


if (ascii_to int (argv[2], &stop_ line) == -1) 
printf ("REMOVE invalid stop line %d\n", argv[2]); 


if (argc >= 4) 
if (! (infile = fopen (argv[3], "r"))) 
{ 
printf ("REMOVE error opening %s\n", argv[3]); 
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exit (1); 


if (argc == 5) 

if (! (outfile = fopen (argv[4], "“w"))) 
{ | | | 

printf ("REMOVE error opening %s\n", argv[4]); 

exit (1); 

} 


for (count = 1; fgets (line, sizeof(line), infile); count++) 
if ((count < start _line) || (count > stop line) ) 
fputs (line, outfile); 


With Turbo C, developing useful utility programs is quite 
straightforward. Experiment with the programs in this chapter 
and you should be able to assemble a library of countless utility 

programs. _ 


Array 
Manipulation 


Because of the tremendous use of arrays in string manipulation, 
most Turbo C programmers have a solid foundation from which to 
build a library of array-manipulation routines. Throughout this text, 
routines have been as generic as possible. This practice has greatly 
increased the number of applications that can use the functions 
without modification of the code of the routine. This chapter exam- 
ines routines that manipulate arrays. In an effort to limit the dupli- 
cation of code, a reduction has been made to the amount of coding 
and testing that must be performed when modifications are made. 
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Array Considerations 


One of the most difficult functions to consider when developing a 
library of array-manipulation routines is how to deal with different — 
array types. For example, the following routine returns the sum of 
the values contained in an array of type float: 


float sum_array (float array[], int num_elements) 
float result = 0.0; 
int i; 


for (i = 0; i < num_elements; i++) 
result += array[i]; 


return (result); 


The array type and value returned from the function are of the type 
float. Although this routine works for floating-point values, the rou- 
tine must be duplicated for an array of type int. Although this 
appears to be a simple fix, remember that Turbo C has many types, 
including the following: 


int float char long int | 
unsigned int double short int 


As a result, you can quickly create several different functions, each 
of which performs an identical task. 

When you create array-manipulation routines, you have three 
alternatives. The first, which was just discussed, is simply to create 
duplicate routines for the required type, as shown here: 
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long int sum_array (int array[], int num_elements) 
int result = 0; 
int i; 


for (i = 0; i < num_elements; i++) 
result += array[iJ; 


return (result); 


However, the shortcoming of this solution is the proliferation of rou- 
tines required for different array types. 

The second alternative is to develop a routine based on the two 
user-defined types shown here: 


typedef int array type; 
typedef int result_type; 


The array-manipulation routine is now defined as follows: 


result_type sum_array (array type array[], int num_elements) 
result _type result = 0; 
int i; 


for (i = 0; i < num_elements; i++) 
result += array[i]; 


return (result); 


To use this routine for an array of type float, change the user- 
defined types, as shown here: 


typedef float array type; 
typedef float result_type; 
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This processing restricts duplication of code, but it too has lim- 
itations. With each application you must recompile the array-manip- 
ulation routines to be sure that the correct types are used. In addi- 
tion, if your program must use several arrays of differing types, this 
method supports only one array type. 

The third alternative requires the user to specify the array type 
as a parameter, as shown here: 


sum_values (array, num_elements, type); 


In this case, type is defined as 


char 
int 
float 

long int 
unsigned int 
double 
short int 


AF WN FH © 


Rather than passing an array of type int, float, or double to the rou- 
tine, the user instead passes an array whose type is defined by a 
union, as shown here: 


union array types { 
char cval; 
int ival; 
float fval; 
unsigned int uval; 
double dval; 
short int sval; 
} 3 
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Within the routine, you access the correct type based on the type of 
variable, as shown here: 


double sum_array (union array types array([], 
int num_elements, int type) 
{ 


double result = 0.0; 
ian. 13 
for (i = 0; i < num_elements; i++) 


Switch (type) { 
case 0: result += (double) array[i].cval; 


break; 

case 1: result += (double) array[i].ival; 
break; 

case 2: result += (double) array[i].fval; 
break; 

case 3: result += (double) array[{i].uval; 
break; 

case 4: result += (double) array[i].dval; 
break; 

case 5: result += (double) array[{i].sval; 
break; 


} 


return (result); 


The following program uses this routine to display the sum of the 
values in several types of arrays by using a single array to sum 
them: 


main () - 
{ 
union array types a[10], b[10], c[{10]; 


double sum_value (union array types *, int, int); 
int a:3 


for (i = 0; i < 10; i++) 
{ 
afi].ival 
b[{i].cval 
c{i].fval 
} 


How at 
Wr OU 
e = 


printf ("int ARRAY %f\n", sum_array (a, 10, 1)) 
printf ("char ARRAY %f\n", sum_array (b, 10, 0) 
printf ("float ARRAY %f\n", sum_array (c, 10, 2 
} 


) 
) 


); 
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The difficulty of this type of routine is that you must now assign 
values to the correct union members, as shown here: 


for (i = 0; i < 10; i++) 
{ 


afi]).ival iors 
b[i].cval 1; 
c[i].fval 330; 


} 


This may be an unreasonable requirement to place on all your 
programs. 

Multiple array types can be quite frustrating to Turbo C pro- 
grammers. The development of your array-manipulation routines is 
a tradeoff among the eq emane factors: 


¢« Duplication of code for each type 
¢ Code recompilation with each application 


e Impact upon code outside of the function (unions) 


The routines in the remainder of this chapter are based on the 
types array_type and return—type. For example, if your array 
types were of type int, you would simply place the following typedef 
statement at the beginning of your program: 


typedef int array type; 
typedef int result_type; 


If you were using arrays of type float, you would use the following: 


typedef float array type; 
typedef float result type; 


Within your programs, you define your array in terms of these two 
types: ; 
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typedef float result _ type; 
typedef float array type; 


main () 


array type salary[50]; 


If you are building a library of routines, you may want to change the 
names of each routine to reflect its type, as shown here: 


float__sum_values 
int__sum__values 
double__sum__values 


Array-Manipulation Routines 


The first routine, sum_—array returns the sum of all of the values 
contained in an array: 


array__type array []; 


. sum__values 
int num__elements= 10; 


Sum of array values 


result _type sum_array (array, num_elements); 
Return the sum of the values in an array. 


array (in): array containing the values to sum. 
num_elements (in): number of elements in the array. 


sum = sum_array (scores, 10); 


+ + + ££ FE HH eK KH K€ OF 


254 TURBO C PROGRAMMER’S LIBRARY 


* This routine requires you to define the types result type 
* and array type as required depending upon your array type. 
. 


*/ 

result_type sum_array (array_type array[{], int num_elements) 
int i; 
result_type result = 0; 


for (i = 0; i < num_elements; i++) 
result += array[i]; 


return (result); 
} 


~The next routine, average_value, returns the average of the 
values contained in an array. | 


_array__type array []; _ 


; | ~~ average__value 
int num_elements=30; Sains 


Average of the values in the array 


™ 
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result_type average value (array, num_elements); 
Return the average value in an array. 


array (in): array containing of values to compute the average of. 
num elements (in): number of elements in the array. 


avg = average value (scores, 10); 


This routine requires you to define the types result type 
and array type as required depending upon your array type. 


/ 


result type average value (array type array[], int num_elements) 
( 


Int i; 
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result type result = 0; 


for (i = 0s < num_elements; i++) 
result += arrayl[il]; 


return (result / num_elements) ; 


} 


The routine minimum—value searches the elements of an array 
and returns the smallest value found, as follows: 


array__type array []; 
int num__elements=30; 


minimum__value 


Smallest value in the array 


[* : | 

* result_type minimum _value (array, num_elements) ; 

* 

* Return the smallest value in an array. 

* 

* array (in): array of values to return minimum value from. 
* num_elements (in): number of elements in the array. 

* 

* min = minimum_value (scores, 10); 

x 

* This routine requires you to define the types result_type 
* and array type as required depending upon your array type. 
* : 

* 


/ 
result type inital: Value (array type array[], int num_elements) 
on 1? 
result_type minimum = array[0]; 
for (i = 1; i < num_elements; i++) 
if (minimum > array[i]) 


minimum = array[i]; 


return (minimum) ; 


¥ 
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The routine maximum_—_value returns the largest value in an 
array, as shown here: 


array__type array []; 


maximum__value 
int num_elements=30; 


Largest value in the array 


result_type maximum _value (array, num_elements) ; 
Return the largest value in an array. 


array (in): array of values to return maximum value from. 
num_elements (in): number of elements in the array. 


max = maximum_value (scores, 10); 


This routine requires you to define the types result_type 
and array type as required depending upon your array type. 


/ 
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result_type maximum value (array type array[], int num_elements) 
vice ase 
result type maximum = array[0]; 
for (i = 1; i < num_elements; i++) 
if (maximum < array[i)) 


maximum = array[i]; 


return (maximum) ; 


The routine median_value returns the median value (middle 
value) contained in an array. Given the array 
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~<q———-- Median value 


the routine median—value returns the value 30. However, if the 
array contains an even number of elements, 
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The values must be in ascending order or median__value returns the 
error status —1. 


array__type array []; 
int num__elements=20; - 
int «status; 


median__value 
O If successful 
—1 If values are not ascending 


#- Median value in the array 


result_type median value (array, num_elements, status); 

Return the largest value in an array. 

array (in): array of values to return median value from. 
num_elements (in): number of elements in the array. 

status (out): 0 if successful, -1 if elements are not ascending. 


median = median value (scores, 10); 


This routine requires you to define the type array type 
as required depending upon your array type. 


/ 
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float median value (array_type array[], int num_elements, int *status) 


{ 


Int. 33 
result _type median; 
*status = 0; 


/* insure array is ascending */ 
for (i = 0; i < num_elements-1; i++) 
if (array[i] > array[i+1]) 
*status = -1; 


if (! *status) 
if (num_elements % 2) 
median = array[{num_elements / 2]; 
else 
median = (array[num_elements / 2] + 
array[num_ elements - (num_elements / 2) - 1]) / 2; 


return (median); 


} 
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The routine modal_value returns the modal value of an array. 
The modal value is simply the value that occurs most often in the 
array. For example, given the following array, 


- the modal value is 2. As was the case, with the routine median 
value, the values of the array must be in ascending order. Given the 
following array, 


= Modal value 


the routine modal_value returns the value 10. If duplicate modal 
values exist, 
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the routine returns the status value 1. 


array__type array []; 
int num__elements=30; 


modal__value —1 If values are not ascending 


int «status; 0 If successful 
1 If duplicate modes 
Modal value in the array of values 
/ 
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result_type modal_value (array, num_elements, status); 

Return the modal value of an array. 

array (in): array of values to return modal value from. — 

num_elements (in): number of elements in the array. 

status (out): 0 if successful, -1 if values not ascending, 
1 if duplicate modes 

mode = modal value (scores, 10, &status) ; 


This routine requires you to define the types result_type 
and array type as required depending upon your array type. 
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result type modal value (array type array[], int num_elements, 
int *status) 
{ 


int i, current count, max count = -1; 
array type current value, max value = 0.0; 
*status = 0; 


/* insure array is ascending */ 


for (i = 0; i < num_elements-1; i++) 
if (array{i] > array[it+1l]) 
*status = -1; 
if (*status != -1) 
{ 
i = 0; 


while (i < num elements) 
{ 
current value = array[il]; 
current count = 0; 
while ((array[i] == current_value) && (i < num_elements) ) 
; 
current _counttt; 
i++; 
} 
if (current_count > max_count) 


max count = 
max value = 
*status = 0; 
} 

else if (current_count == max_count) 


current_count; 
current value; 


*status = 1; /* duplicate mode */ 
} 
} 


return (max value); 


} 


Variance and Standard 
Deviation 


Two of the most widely used statistical tools are variance and stan- 
dard deviation. Statisticians use them to analyze the expected value, 
or average of a population. For example, if 100 different programs 
are run on two computers, an expected value can be computed that 
represents how much faster the first computer is in comparison to 
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the second. Statisticians can use either the variance or standard 
deviation to determine the accuracy of the expected value by describ- 
ing the average deviation from the sample mean. 

The variance is computed by using the following equation: 


The standard deviation is computed by taking the square root of the 
variance, as shown here: 


In both equations, N represents the number of elements in the mean 
of the sample. | 

The standard deviation is more important than variance because 
its result is more readily understood. In the example just given, if 
the first computer averages 3 seconds faster than the second comput- 
er, possible values would be as follows: | 
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Expected value: 3 seconds 
Variance: 4 (seconds) 
Standard deviation: 2 seconds 


When the variance is calculated, the difference between each 
element and the mean is squared to produce only positive values. 
The following routine determines the variance of the values in an 
array: 


array__type array []; 
int num—elements=25; 


variance 


Variance of the values in the array 


/* 

* float variance (array, num_elements) 

* 

* Return the variance of values in an array. 

* 

* array (in): array of values to return variance of. 

* num_elements (in): number of elements in the array. 

x 

* var = variance (scores, 10); 

* 

* This routine requires you to define the type array type 

* as required depending upon your array type. This routine 
* uses the routine average value contained in the array library. 
* 

al 


float variance (array type array[], int num_elements) 
ae 1:3 
float sum = 0.0; 
array type average, average value (array type *, Ine); 


average = average value (array, num_elements); 
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0; i < num_elements; i++) 
(array[i] - average) * (array[i] - average); 


return (sum / num elements) ; 


} 


The routine standard—deviation returns the standard deviation of 
the values in an array: 


array__type array []; - 
int num__elements=30; — 


standard__deviation 


Standard deviation of 
the values in the array 


float standard_ deviation (array, num_elements) 
Return the standard deviation of values in an array. 


array (in): array of values to return standard deviation of. 
num_elements (in): number of elements in the array. 


stddev = standard deviation (scores, 10); 
This routine requires you to define the type array type 


as required depending upon your array type. This routine 
uses the routine variance contained in the array library. 


+ + + * Fe HF HF F HF HF KH H HK F 
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#include <math.h> 
float standard deviation (array type array[], int num_elements) 
float variance (array type *, int); 


return (sqrt((variance (array, num_elements) * num_elements) / 
(num_elements - 1))); 


} 


Least Squares Fit 


The least squares fit is one of the simplest methods used to deter- 
mine the linear equation that best fits a collection of data values. For 
example, given the following distribution of values, 


30K 
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the least squares algorithm provides a linear equation that best fits 
the data, as shown here: 


Dollars Earned 


5K 


1K 2K 3K 4K SK 6K 7K 8K 9K_ 10K 


Advertising Expense 


The line shown is called the line of best fit. The slope and inter- 
cept of this line are used to determine missing points in your data. 
Linear equations are expressed in slope-intercept format. 

The procedure least—square returns the slope and intercept of 
the line that best fits the data. | 


array__type xarray []; 
array__type yarray []; 
int num__elements=30; least__square 


array__type «slope; 5 Slope of line 
array__type «intercept; O Intercept 
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/* 

* void least_square (x, y, num_elements, slope, intercept) 
* 

* Return the slope and intercept of the line that best fits 
* the x and y data values given. 

* 

* x (in): array of x coordinates. 

* y (in): array of y coordinates. 

* num elements (in): number of elements in the array. 

* slope (out): slope of the line. 

* intercept (out): intercept of the line. 

* 

* least square (x, y, 10, &slope, &intercept) ; 

* 

* This routine requires you to define the type array type 
* based upon the type of your array. 

* 

*/ 


void least square (array type x[], array type y[], int num_elements, 
float *slope, float *intercept) 
{ 


float xsum = 0.0, ysum = 0.0, xsquared_ sum = 0.0, xy_sum = 0.0; 
ine: 4. 


for (i = 0; i < num_elements; itt) 
{ 
xsum += x[i]; 
ysum += y[il]; 
xsquared sum t= x[i] * x[il; 
xy sum += x[i] * y[il; 


} 


*slope = ((xsum * ysum) - (num_elements * xy _sum)) / 
((xsum * xsum) - (num_elements * xsquared_ sum) ); 
x*intercept = (ysum - (*slope * xsum)) / num_elements; 


} 


Once you know the slope and intercept for the data, you can use 
them to estimate missing points, as shown here: 


slope = 5 intercept = 1 
x= 1.5 

y = slope * x + intercept 

y = slope * 1.5 + intercept 


y—5*1571 
y= 75+ 1 
y = 8&5 
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Statisticians use residuals to determine the goodness of fit of the 

_ linear equation produced by least—square. A residual value is the 

distance between each value and the line of best fit. For example, © 

the difference between the actual value of Y and the approximated 
value Y’ can be computed by the following equation: 


RESIDUAL = Y — Y’; 


The sum of the residuals for an array can determine the validity 
of the linear equation. For example, if the data is linear, 
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the sum of the residuals will be 0. As the line less approximates the 
data this sum will be greater, as shown here: 
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Dollars Earned 
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Using Macros 


Many Turbo C programmers must often balance the increased code 
size produced by C macros (over that of functions) against their 
increased flexibility. Developing generic array-manipulation rou- 
tines in Turbo C is not an easy task. However, you can often use 
macros instead to increase the flexibility of your code. For example, 
the following macro returns the sum of the elements in an array: 


#define sum_array(array, num_elements, rslt) 


int index = 0; 

rslt = 0; 

while (index < (num_elements) ) 
rslt = rslt + array[index++]; 


a an an a a 
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Note the differences between the macro code and the routine 
presented previously in this chapter. First, because the code is a 
macro and not a function, it does not return a value. You must pass a 
parameter to the macro that will store the result, as shown here: 


#define sum_array(array, num_elements, rslt) © \ 


Second, because the macro does not define an array type, it will 
work without modification for arrays of any type. For example, the 
following program obtains the sum of arrays of type int and float by 
using the single macro: 


#define sum_array(array, num_elements, rslt) 


int index = 0; 

rslt = 0; 

while (index < (num_elements) ) 
rslt = rslt + array[indext+]; 


> a a aa aa aa ae 


main () 
{ 
int int_array[10], int_result; 
float float_array[10], float_result; 
int i; 


for (i = O; i < 10; i++) 
{ 
int_array[i] = i; 
float_array[i] = i; 


sum_array(int_array, 10, int_result); 
sum_array(float_array, 10, float_result); 


printf ("Result of int array sum %d\n", int result); 
printf ("Result of float array sum %f\n", float _result); 


All of the routines in this chapter can be implemented as macros 
in this fashion. In many cases, your code will actually execute 
slightly faster since you do not have the stack overhead associated 
with functions. The tradeoff, however, is increased code size. 
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Multidimensional Arrays 


All of the arrays presented thus far have been single-dimensional 
arrays like the following: 


float scores [10] 
int grades [5]; 


However, many applications require arrays of multiple dimensions, 
as shown here: 


float box [3][31; 
int tax_table [3] [5][10]; 


Because of the way that Turbo C usually stores arrays, you can nor- 
mally pass single-dimensional or multidimensional arrays to your 
functions without modification to the code. For example, assume you 
have the array shown here with the values given: 


int X[3] [3]; 


In most cases, Turbo C actually stores the array as a single- 
dimensional array, as follows: 
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Thus, you can normally pass the array to your array-manipulation 
routines regardless of the number of dimensions. Simply remember 
to pass the correct number of elements, as shown here: 


float box [8][8] has 3 * 3, or 9, elements 
int tax_table [8][5][10] has 3 * 5 * 10, or 150, elements 


In most cases, despite the number of dimensions, the routines pre- 
sented work without modification. Experiment with these routines 
and you should find that they are quite flexible. If you are using 
arrays of pointers, be aware of the fact that Turbo C is not required 
to store arrays in a linear manner. The only ANSI requirement is 
that array[i] is directly equivalent to *((array)+(i)). As a result, you 
will likely need to modify your array-manipulation routines. 

Admittedly, many of the routines presented in this chapter are 
quite simple. However, by creating libraries of routines like these, 
your program development becomes much simpler and much faster. 
Remember that these library routines are your building blocks for 
larger programs. 


Searching 
and Sorting 


Many applications that use arrays to store data also perform table 
look-ups. These applications search for specific values (or process 
the data contained in the array) with the assumption that the data is 
in either ascending or descending order. Searching and sorting 
operations are important aspects of most computer applications. 
Choosing the correct sorting or searching algorithm has a signif- 
icant impact on the execution time of your programs. 

Computer scientists have thoroughly researched the characteris- 
tics of sorting and searching algorithms. They found that several 
algorithms execute much faster because fewer iterations are 
required to sort an array or to locate a specific value. 
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This chapter discusses sequential and binary searches. The sort- 
ing algorithms in this chapter include the bubble, selection, Shell, | 
and quick sorts. As in Chapter 10, the routines are as generic as 
possible. Each routine is based on the user-defined type array—type. 
To minimize duplicate sorting routines, the sorting order (either 
ascending or descending) is a parameter to each routine. 


Searching 


Many programming applications must search arrays for specific 
values. For example, assume that the following arrays contain 
employee information: 


Boy 30000 
Burnham | 45000 
Byrd 38000 _ 
Davis 25000 
Eubank 60000 
1 Grant | 35000 
Jones 45000 
Kempf 90000 


Rosaschi | 55000 


Watson 32000 


Index EMPLOYEE ID NUMBER SALARY 
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If management wants to access the salary of Jones, a program can 
sequentially search the array employee until the name is found. The 
program can then locate the salary associated with the index value 
that points to Jones. In this case, index 6 points to a salary of 
$45,000. The goal of the search routines presented here is to locate a 
value and return the corresponding index. If the value is not found, 
each routine will return the value —1. 


Sequential Search 


The sequential search is the simplest searching algorithm. The 
values to be examined here are stored as elements in the array. 
Each time a value must be found, the sequential search starts with 
the first element in the array. The search examines the elements one 
after another until either the value is found or the array elements 
are exhausted. In the example of the employee information array, 
the search would first test the element Boy and then examine suc- 
cessive values of the array until it found the element Jones. The fol- 
lowing routine implements the sequential search: 


array__type desired__value; 
array__type values[10]; = sequential__search 
int num__elements = 10; 


Index value associated 
with desired__value or 
—1 if not found 


sequential search (value, array, num_elements) 


Sequentially search the array of values given in order to locate 
a specific value. Return the index of the value, or -1 if the 
value is not found. 


+ + * * * 
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* 
* value (in): Value to search for. 
* array (in): Array of values to examine. 
* num_elements (in): Number of elements in the array. 
n 
* index = sequential search (5, scores, 10); 
* 
* If multiple occurrences of. the same value are present in the 
* array, this routine returns the index of the first occurrence. 
x 
ae 


int sequential search (array type value, array type values[], 
int num-elements) 
; 


int i, location = -1; 
for (i = 0; (i < num elements) && location == -1; i++) 
if (value == values[i]) 


location = i; 


return (location); 


Keep in mind that you can again use C macros in order to increase 
the generic nature of each routine. For example, this macro imple- 
ments a generic segmental search: 


se a seq_search(value, values, num_elements, location) \ 
int k; \ 
location = -1; \ 

\ 

for (k = 0; (k < num_elements - 1) && location == -1; k++) \ 
if (value == values [k]) \ 
location = k; \ 


This technique can be used for all of the routines presented in this 
chapter. The drawback, however, is increased code size. 


Binary Search 


In the previous application, the sequential search successfully found 
the desired information. In many cases, you can reduce the number 
of iterations the routine must perform to find the data by using a 
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different searching algorithm, such as the binary search. To per- 
form a binary search, the values in the array must be in order, tra- 
ditionally ascending order (lowest to highest). 

The binary search is one of the quickest searching algorithms 
used by programmers. Unlike the sequential search (which exam- 
ines successive elements of the array), the binary search reduces the 
number of elements that must be examined (by a factor of two) with 
each iteration, until the desired record is found. 

This process is similar to the one you use when you look up a 
telephone number. Assume that you are looking up the name Jones. 
You will probably start near the middle of the book. If the names on 
that page begin with a letter other than “J,” you have effectively cut 
in half the number of pages you must search for the name. If the 
name Jones is not on this page, you simply repeat this process until 
the name is found. 

Admittedly, you could have used a sequential search to find the 
name Jones by starting at the first page in the telephone book and 
examining every page. In a small town, this might not take long. 
However, in a city such as New York, a sequential search would take 
far too much time. 

You could use the sequential search to search the array of 
employee information for the salary of Jones. The process requires 
seven iterations, but the binary search requires only four iterations. 
This obviously reduces the execution time of the program. The 
decrease in execution time becomes important as array sizes 
increase. | 

The first iteration of the binary search examines the entire array 
(just as you examined the entire telephone book). Using the employee 
information example, the variables low and high are assigned the 
values 0 and 9. The variable mid—index is the middle element in the 
search range. The array element values[mid—index] contains the 
value that you will compare to desired—value. To calculate mid— 
index, use the following line: 


mid_index = (high + low) / 2; 
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Since the routine performs integer division, mid—index is assigned 
the value 4, as shown here: 


<«— MID__INDEX 


If the value contained in values[mid—index] equals the desired 
value, the search is completed by setting a variable called found to 
true. 

If the value contained in values[mid—index] is greater than the 
desired value, the algorithm modifies the search range because the 
value indicates that searching past that point for the desired value is 
not necessary. For example, if the array contains the following, 
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<= MID__INDEX 


and you are searching for Jones, you have no reason to search above 
values[index] for the value. The search then modifies the value of 
high as follows: 


high = mid_index - 1; 


In effect, this process creates a new range of names to examine. 
The value of mid__index must also be modified, as shown here: 
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mid index = (high + low) / 2; 


The new range of names then contains the following: 


ae ech 


in 


<«— MID_INDEX 
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and you are searching for Jones, you need not search below 
values[mid—index] for the value. The search modifies the value con- 
tained in low by the following statement: 


low = mid_index + 1; 


This statement then produces this new range: 


The algorithm recomputes mid—index to yield 
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After the desired value is found, the variable found terminates © 
the search. If the value is not found, a secondary test is required. For 
example, if the array contains | 


tor 


<— MID_INDEX 


<t— HIGH . 


and the desired value is Jones, the first iteration modifies high and 
mid—index as follows: 


0 <— LOW 

1 <q— MID_INDEX 
“— HIGH 

2 


The second iteration produces 


ae LOW 


<«— MID__INDEX 
| “™~ HIGH 
Parrish 
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The third iteration illustrates the error that occurs if the algo- 
rithm does not perform the secondary test that prevents the array 
boundaries from being overrun, as shown here: 


oan, 
arnes | <— MID_INDEX 


Kempf ~<«— LOW 


If the desired value is not found, the algorithm attempts to access 
invalid subscripts, which results in an error. The complete test 
necessary to prevent this error becomes 


while ((! found) && (high >= low) ) 


If the desired value is not found, the variable found remains false 
and should be examined by the calling routine. 
The following routine implements the complete binary search: 


array__type desired_value; 
array__type values[10]; binary__search 
int num__elements = 10; 


Index value associated 
with desired__value or 
—1 if not found 
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binary search (value, array, num_elements) 


Use a binary search of the array of values given in order to locate 
a specific value. Return the index of the value, or -1 if the 
value is not found. 


value (in): Value to search for. 
array (in): Array of values to examine. 
num_elements (in): Number of elements in the array. 


index = binary search (5, scores, 10); 


+ ++ + Fe + FF HF FF 


™~ 


int binary search (array type value, array type values[], 


Sorting 


int num_ elements) 


{ 
int found = 0; 
int high, low, mid index; 


low = 0; 
high = num elements; 
mid index = (high + low) / 2; 


while ((! found) && (high >= low) ) 
{ 


if (value == values[mid index] ) 
found = 1; a 

else if (value < values[mid_index]) 
high = mid_index - 1; 

else if (value > values[mid_index]) 
low = mid_index + 1; 

mid index = (high + low) / 2; 


return ((found) ? mid_index : -1); 


} 


Many programming applications require that data be processed in 
either ascending (lowest to highest) or descending (highest to lowest) 
order. In such instances, a sorting algorithm must be used to place 
the data in order. The sorting algorithms introduced in this chapter 
are the bubble sort, the selection sort, the Shell sort, and the quick | 
sort. : | 

All of the array-manipulation routines in Chapter 10 were based 
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on the type array—type. Consequently, duplicate routines for arrays 
of different types did not have to be developed. Remember, if you 
develop two routines to sort data in ascending and descending order, 
your programming efforts have been needlessly duplicated. To avoid 
duplicate routines, the sorting algorithms provided in this chapter 
allow you to specify as a parameter the desired order (ascending or 
descending), as shown here: 


Value Sort Order 


0 Ascending 
Descending 


Bubble Sort 


The bubble sort is a popular sorting algorithm because of its simplic- 
ity. It is so named because with each iteration, a value rises (like a 
bubble) to the top of the array. The bubble sort gets values in the 
correct order by comparing adjacent array elements and exchang- 
ing those that are out of sequence. Because of this, the number of 
iterations the bubble sort requires makes it an inefficient sort for 
large arrays. If your array contains more than 380 elements, you 
should use either the Shell sort or the quick sort. 
Assume that the array values contain the following: 
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The first iteration of the bubble sort for ascending order will per- 
form four evaluations: 


Since the largest value in the array is in the correct location after 
the first iteration, the algorithm examines only the first four ele- 
ments on the second iteration: 


In the third iteration, only two elements are examined: 
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The final iteration ensures that the first two array elements are in 
the correct order: 


Result 
0 0 
1 1 
2 2 
3 3 
4 4 


The following routine implements the bubble sort: 
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array__type values[10]; 


——m Sorted array 
int num__elements = 10; 3 bubble__sort 7 


int sorting—order = 0; 


void bubble sort (values, num elements, order) 
Sort the array of values in the order specified. 


values (in/out): Array of values to sort. 
num_elements (in): Number of elements in the array. 
order (in): Desired sorting order: 

0 for ascending 

1 for descending 


bubble sort (values, 10, 1); 


/ 
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void bubble sort (array type values[], 
int num_elements, int order) 
{ 


array type temp; 
Init; Ws 


for (i = 0; i < num_elements - 1; itt) 
for (j = i+ 1; j < num elements; jt+t) 
if ((! order && (values[i] > values[j 
(order && (values[i] < values[4]) 
{ 
temp = values[iJj; 
values [i] values[j]; 
values [4] temp; 


} 


})) UI 
)) 


toll 


Selection Sort 


The selection sort is another simple sorting algorithm. Although 
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most schools teach the bubble sort, many programmers find that the 
selection sort is easier to understand and to use without losing 
efficiency. 

In the selection sort, elements are sorted by selecting the maxi- 
mum or minimum value (depending on ascending or descending 
order) with each iteration. 

Assume that the following array is sorted in ascending order: 


The first iteration selects the minimum value and places it in the 
first element. To accomplish this iteration, the sort first selects the 
first element as the current index. The sort then compares elements 
in the array to values[current]. If one of the values is greater, the 
two values are exchanged. | 

The first iteration selects the minimum value as follows: 
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The second iteration places the second smallest value in element 2: 


The third iteration selects the third smallest value: 


The fourth iteration results in the sorted array: 


Result 


The following routine implements the selection sort: 
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array__type values[10]; Sorted array 
int num__elements = 10; selection__sort 
int sorting__order = 0; 


void selection_sort (values, num_elements, order) 
Sort the array of values in the order specified. 


values (in/out): Array of values to sort. 
num elements (in): Number of elements in the array. 
order (in): Desired sorting order: 

0 for ascending 

1 for descending 


selection_sort (values, 10, 1); 


/ 
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void selection_sort (array type values[], int num_elements, int order) 
{ | 
array type temp; 


int j, current; 
for (current = 0; current < num_elements - 1; current++) 


for (j = current + 1; j < num_elements; j++) | 
if ((! order && (values[current] > values[j])) |] 
(order && (values({current] < values[j]))) 
{ 


temp = values([current]; 
values[current] = values[j]; 
values[j] = temp; 


} 
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Shell Sort 


To enhance the efficiency of sorting algorithms for large arrays, 
Donald Shell created a sorting algorithm that is now called the Shell 
sort. The Shell sort differs from the bubble sort in that it compares 
elements that are spaced farther apart before comparing adjacent 
elements. This removes much of the array’s disorder in early itera- 
tions. 

The Shell sort uses a variable called gap that is initially set to the 
value of one-half of the number of elements in the array. The value 
of gap specifies the distance between each pair of comparison ele- 
ments in the array. In the following example, the elements com- 
pared will initially be separated by a gap of 4: 


For the first iteration of the sort, gap is assigned a value of 4. This 
iteration of the array compares all of the elements separated by this 
distance. The process is repeated until no exchanges occur with a 
gap of 4: 
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When no more exchanges can occur with a gap of 4, the algo- 
rithm modifies gap to gap / 2. The elements separated by a gap of 2 
are then compared until no exchanges occur: 
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When no more exchanges can occur with a gap of 2, gap is again 
modified to gap / 2, and the process is continued with a gap of 1. 
When no exchanges occur with a gap of 1, gap is assigned the value 
of gap / 2. In this case, integer division assigns gap the value of 0, 
which is the ending condition: | 


No exchanges 


The following routine implements the Shell sort: 


_ array_type values[10]; | Sorted array 
int num__elements = 10; shell__sort 
int sorting__order = 0; | 
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/* 
* void shell sort (values, num_elements, order) 
* 
* Sort the array of values in the order specified. 
* 
* values (in/out): Array of values to sort. 
* num_elements (in): Number of elements in the array. 
* order (in): Desired sorting order: 
me 0 for ascending 
* 1 for descending 
k 
* shell sort (values, 10, 1); 
* 
*/ 


void shell sort (array type values[], 
‘int num_elements, int order) 
{ 


array type temp; 
int i, gap, exchange occurred; 
gap = num_elements / 2; 


do 
do { 
exchange occurred = 0; 


for (i = 0; i < num_elements - gap; i++) 
if ((! order && (values[i] > values[itgap])) || 
(order && (values[i] < values[itgap]))) 
{ 
temp = values[i]; 
values[i] = values[itgap]; 
values[itgap] = temp; 
exchange occurred = 1; 


} 


while (exchange occurred) ; 
while (gap = gap / 2); 
} 


Quick Sort 


Although the efficiency of the Shell sort increases as the number of 
elements in the array increases, it, too, has limitations. The quick 
sort (which is often implemented recursively) increases the speed of 
the sort as the number of elements in the array approaches 150 to 
200 elements. In fact, the quick sort is one of the fastest array- 
sorting algorithms in use today. 
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The quick sort sorts data by breaking a list of values into aseries | 
of smaller sorted lists. For example, if the array 


START 0 


END_LIST 8 


is passed to the quick sort routine, the, algorithm will select the 
value contained in values[(start+end_list) / 2] (which in this case is 
values[4]) as the list separator. Any values in the list that are less 
than or equal to the list separator are placed in one list, and the 
values that are greater than the list separator are placed into a 
second list, as shown here: 
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END_LIST 


The same process is carried out on each sublist, or range, until 
each contains only one element. At that point, the array will be. 
sorted. 

Figure 11-1 illustrates the sequence in which the sublists are 
constructed. The sort splits the list into two parts: The smaller 
items are placed in the left-hand list, and the larger items into the 
right-hand list. The process is repeated until there is only one item 
in each list and the items are sorted from left to right. 

As another example, imagine that the following array 
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LIST__.SEPARATOR = 400 


END__LIST 


is passed to the quick sort routine to be sorted in ascending order. It 
is first divided into two lists. The variable low is assigned to the first _ 
element in the list. The variable high is assigned to the last element 
in the list. The variable low is then incremented until values[low] 
contains a value that is greater than or equal to the list_separator 
(for descending order, the value must be less than the list— 
separator). 


while (values [low] < list separator) 
low++; 
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Figure 11-1. Sequence of sublist construction using a quick sort 


When values[low] contains a value that is greater than or equal to 
the value contained in the list__separator the while loop terminates. 
The value in high is then decremented until values[high] contains a 
value that is less than or equal to the list__separator: 


302 TURBO C PROGRAMMER’S LIBRARY 


LIST_. SEPARATOR 


END_LIST 


When the value contained in values[high] is less than or equal to the 
value contained in the list__separator the while loop terminates and 
the values contained in low and high are compared. If the value in 
low is less than the value in high, the values are exchanged; the 
value in low is incremented while the value in high is decremented, 

as Shown here: | | 


if (low <= high) 
{ 


temp = values[low]; 
values[low++] = values[high]; 
values [high--] = temp; 

} : 
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This process is repeated until low is greater than high. 

Once the value in low is greater than the value in high, you have 
two lists. The first contains the elements from start to high, and the 
second contains the elements from low to end__list: 


LOW 


END__LIST 


END_LIST 


Each list then is passed recursively to the routine, and each is also 
subdivided into lists. This process will continue until each list con- 
tains only one element. 

The following routine implements the quick sort: 
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array__type values[10]; . Sorted array of values 
int start = 0; | 


int end__list = 9; quick__sort 


int sort__order = 0; 


/ * 
* void quick sort (values, first, last, order) 
* : é i 
* Sort the array of values in the order specified. 
* 
* values (in/out): Array of values to sort. 
* first (in): Index of the first element in the list to sort. 
* last (in): Index of the last element in the list to sort. 
* order (in): Desired sorting order: 
‘] 0 for ascending 
. 1 for descending 
* 
* quick sort (values, 0, 9, 1); 
* ; 
* 


/ 


void quick sort (array type values[], int start, 
int end_list, int order) 
{ 


array type temp; 

int low = start; 

int high = end_list; 

int list_separator = values [(startt+end_list) / 2]; 


do { , 
if (! order) /* ascending */ 
{ 
while (values[low] < list separator) 
lowtt+; — 


while (values[high] > list_separator) 
high--; 


else /* descending */ 
{ 
while (values[low] > list _separator) 
lowt+t+; . 


while (values[high] < list separator) 
hagh=—; 
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} 


if (low <= high) 


{ 
temp = values [low]; 
values[low++] = values[high]; 


values[high--] = temp; 
} 


} 
while (low <= high); 


if (start < high) 
quick sort (values, start, high, order); 


if (low < end_list) 
quick sort (values, low, end_list, order); 
} 


Arrays of Character Strings 
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All of the arrays presented thus far have been arrays of type, int, 
float, double, and so on. Turbo C also allows you to create arrays of 
character strings (argv and env). Just as you traverse arrays of type 


float with an index value, 


for (i = O; i < 10; i++) 
printf ("%f\n", floating point values [1i]); 


arrays of character strings are manipulated the same way: 


main (argc, argv) 
int argc; 
char *argv[]; 
{ 
int: is 
for (i = 0; i < argc; itt) 
printf ("%s\n", argv[i]); 
} 
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Although the arrays contain character strings, manipulation of 
the arrays is essentially the same. The same holds true for sorting 
and searching algorithms. The only difference is the code used to 
perform element comparisons. For example, the following program 
uses the routine equal_strings from Chapter 3 to implement a 
sequential search: 


. array__type desired. value; | 
array__type values[10]; | str__sequential__search 
int num__elements = 10; ‘ 


Index value associated 
with desired__value or 
—1 if not found 


str sequential search (value, array, num_elements) 

Sequentially search the array of values given in order to locate 
a character string. Return the index of the value, or -1 if the 
value is not found. 

value (in): String to search for. 

array (in): Array of values to examine. 

num elements (in): Number of elements in the array. 


index = str_sequential search ("Monday", days, 10); 


If multiple occurrences of the same value are present in the 
array, this routine returns the index of the first occurrence. 


/ 
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int str sequential search (array type value, array type values[], 
int num_elements) 
{ 


int i, location = -1; 
for (i = 0; (i < num_elements) && location == -1; i++) 
if (equal_strings (values[i], value, 0)) 


location = i; 


return (location); 
} 
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Assuming that your array contains the following, 


Brown 


Names 


On DO fF WD MBS + OC 


the function invocation 


index = str sequential search ("Roberts", Names, 9); 


returns the index value 5. Likewise, the invocation 


index = str sequential search ("Kellie", Names, 9); 
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returns the value —1 since the array does not contain the string. The 
following routine uses compare_—strings (presented in Chapter 3) to 


implement a binary search: 
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array__type desired__value; 
array__type values[10]; str__binary__search 
int num__elements = 10; 


Index value associated 
with desired__value or 
—1 if not found 


/ * 
* str_binary search (value, array, ~num_elements) 
* . 
* Use a binary search of the array of values given in order to 
* locate a character string. Return the index of the value, or 
* -1 if the value is not found. 
* 
* value (in): String to search for. 
* array (in): Array of values to examine. 
* num_elements (in): Number of elements in the array. 
* 
* index = str_ binary search ("Monday", days, 10); 
* ‘ 
* 


™~s 


int str_ binary search (array type value, array type values[], 
int num_elements) 
{ 


int i, found = 0; 
int high, low, mid_index, result; 


low = 0; 
high = num elements; 


mid index = (high + low) / 2; 
while ((! found) && (high >= low) ) 
( 7 


result = string comp (value, values [mid index], 0).4 


if (result == 0) 
found = 1; 
else if (result == 2) 
high = mid index - 1; 
else if (result == 1) 


low = mid_index + 1; 


mid index = (high + low) / 2; 
} 


return ((found) ? mid_ index: -1); 


of 
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The only real difference between the string-searching routines and 
those presented at the beginning of this chapter is the code that per- 
forms the element comparisons. 


if (value == values[i]) 
Versus 


if (equal _ strings (value, values[i])) 


You can indeed develop a single routine to handle both types. To 
do so, you have a couple of alternatives. 

The first alternative is to pass, as a parameter to the routine, the 
address of a function that is to perform the actual element compari- 
sons, as shown here: 


generic search (value, array, num_elements, compare routine); 


For an array of type float, this routine would be defined as follows: 


float_compare (float a, float b) 
{ 


return (a == b); 


} 


Within a program that uses the array, you would pass the address of 
float—compare to the generic__search routine, as shown here: 


typedef float array type; 

main () 
ee values[10]; 
int generic search (array:type, array type [], int, int (*) ()); 
int i; 


for (i = 0; i < 10; i++) 
values[i] = i * 1.0; 


printf ("Location of %f in array is %d\n", 3.0, 
generic search (3.0, values, 10, float_compare) ); 
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The following code implements the generic search: 


int generic search (array type value, array type values[], 
int num_elements, 
int (*compare) (array type, array type) ) 
{ ; 
int i, location = -1; 
for (i = 0; (i < num_elements) && (location == -1); i++) 
if ((*compare) (value, values[i])) 
location = i; 


return (location); 
} 


Note the definition of the routine that performs the actual compari- 
son of array elements: 


int (*compare) (array type, array type) 


If you examine the contents of the first set of parentheses, you find 
that compare is a pointer. The second set of parentheses indicates 
that it is a pointer to a function. The type int defines the type of 
value returned by the function. This differs greatly from the 
declaration © 


int *compare (array type, array type) 


which declares compare to be a function that returns a pointer to a 
value of type int. 

Knowing this, you can later pass an array of character strings 
and the routine equal__strings to generic__search, as shown here: 


index = generic search ("MONDAY", days, 10, equal strings) ; 


Remember that, although you are using the same routine for each 
type, you must define the type array_type and recompile for each 
type of array. 

Although this algorithm seems powerful because of its use of a 
pointer to a function, it has several drawbacks. First, you may have 
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to create several additional functions to perform your element 
comparisons: 


float_compare (float a, float b) 
{ 
return (a == b); 


} 


int compare (int a, int b) 
{ 
return (a == b); 


} 


double compare (double a, double b) 
: 


return (a == b); 


Remember, function invocations add overhead. This routine greatly 
increases the number of invocations required, since each comparison 
is now a function call. As such, the routine will run slower than 
previous routines. 

A second alternative is to pass the parameter that describes the 
type of array, as shown here: 


Type 


Nonstring array 
Array of character strings 


Within the routine, you simply perform a comparison based on this 
type, as shown here: 


int generic_search (array type value, array type values[], 
int num_elements, int type) 
{ 


int i, location = -1; 
for (i = 0; (i < num_element) && (location == -1); itt) 
if ((type == 0) && (value == values[i])) 
location = i; 
else if ((type == 1) && (equal strings (value, values[i]))) 


location = i; 


return (location); 


} 


This routine requires additional function invocations. You must 
still recompile this routine with each array type. As such, most pro- 
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grammers find it simpler to develop a library of routines for string 
arrays and nonstring array types: 


int bubble sort (values, num_elements, order) ; 
float bubble sort (values, num_elements, order); 
string bubble sort (values, num_elements, order); 


Since you have already seen how the sorting routines work, no 
discussion of implementation is presented here for arrays that con- 
tain character strings. The following routines implement the bubble, 
selection, Shell, and quick sorts for arrays of character strings: 


array__type values[10]; 


a Sorted array 
int num__elements = 10; str__bubble__sort 


int sorting—_order = 0; 


/* 

* void str_bubble sort (values, num_elements, order) 
* 

* Sort the array of strings in the order specified. 
* 

* values (in/out): Array of values to sort. 

* num_elements (in): Number of elements in the array. 
* order (in): Desired sorting order: 

x 0 for ascending 

x 1 for descending 

x 

* str_bubble sort (values, 10, 1); 

x 

x] 


void str_ bubble sort (array type values[], int num_elements, int order) 
array type temp; 
void fast_exchange (); 
int a; 3? 
for (i = 0; i < num_elements - 1; i++) 
for (j = i+ 1; 3 < num elements; j++) 


if ((! order && (string_comp (values[{i], values[j]) ==1 
(order && (string comp (values[i], values[j]) == 2) 


yd) TI 
)) 


fast_exchange (values[i], values[j]); 
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array__type values[10]; Sorted array 


int num__elements = 10; str__selection__sort 
int sorting__order = 0; 


/* 

* void str_selection sort (values, num_elements, order) 
k 

* Sort the array of strings in the order specified. 

* 

* values (in/out): Array of strings to sort. 

* num_elements (in): Number of elements in the array. 
* order (in): Desired sorting order: 

x 0 for ascending 

* 1 for descending 

* 

* str _selection_sort (values, 10, 1); 

k 

* 


/ 


void str_selection_sort (array type values[], 
int num_elements, int order) 
{ 


Int: 22 ly “Current; 


void fast exchange (); 


for (i = 0; i < num_elements - 1; i++) 
{ 
current = i; 
for (j = i+ 1; j < num_elements; jt+) 
| | 


if ((! order && (string comp (values[current], values[j]) = 
(order && (string comp (values[current], values[j]) = 
fast_exchange (values[current], values[j]); 


array__type values[10]; | Sorted array 
int num_elements = 10; str__shell__sort 


int sorting__order = 0; 
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/* 

* void str shell sort (values, num_elements, order) 
* 

x Sort the array of strings in the order specified. 
* 

* values (in/out): Array of.strings to sort. 

* num_elements (in): Number of elements in the array. 
* order (in): Desired sorting order: 

* 0 for ascending 

* 1 for descending 

* 

* str_shell_ sort (values, 10, 1); 

x 

* 


/ 


void str_shell_ sort (array type values[], 
int num_elements, int order) 
{ 


array type temp; 
int i, gap, exchange_occurred; 
gap = num_elements / 2; 


do 
do { 
exchange occurred = 0; 


for (i = 0; i < num elements - gap; itt) 
5 Ds Slam 2 order && (string comp (values[i], values[itgap]) == 1)) | 
(order && (string comp (values[i], values[itgap]) == 2))) 
{ 
temp = values[i]; 
values[i] = values[it+gap]; 
values{itgap] = temp; 
exchange occurred = 1; 
} 
} 
while (exchange_occurred) ; 
while (gap = gap / 2); 
} 


array__type values[10]; Sorted array of values 
int start = 0; 


int end__list = 9; str__quick__sort 
int sort_order = 0; 
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/* 
* void str _quick_sort (values, first, last, order) 

* 

* Sort the array of values in the order specified. 

x 

* values (in/out): Array of values to sort. 

* first (in): Index of the first element in the list to sort. 
* last (in): Index of the last element in the list to sort. 

* order (in): Desired sorting order: 

* 0 for ascending 

= 1 for descending 

* 

* str_quick_ sort (values, 0, 9, 1); 

x 

* 


/ 


void str _quick_sort (array type values[], int start, 
int end list, int order) 
{ 
array type temp; 
int low = start; 
int high = end_list; 
int list separator index = (start+tend_ list) / 2; 


void fast_exchange (); 
char list_separator [128]; 


copy string (values[list_separator index], list_separator, 
sizeof (list_separator) ); 


do { 
if (! order) /* ascending */ 
{ 
while (string_comp (values[low], list _separator) == 2) 
lowt+t; 
while (string _comp (values[high], list_separator) == 1) 
high--; 
else /* descending */ 
{ 
while (string comp (values[low], list separator) == 1) 
lowt++; 
while (string_comp (values[high], list separator) == 2) 
high--; : 


} 


if (low <= high) 
fast_exchange (values[low++], values[high--]); 
} 
while (low <= high); 
if (start < high) 
str_quick_sort (values, start, high, order); 


if (low < end_list) 
str_quick_sort (values, low, end_list, order); 
} 
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‘This chapter was written with two goals. First, to present several 
routines that you can get up and running in a hurry. Second, and 
perhaps more important, to teach you how several of the most popular 
sorting and searching algorithms work. It also is important to point out 
the bsearch, qsort, and lsearch routines in the Turbo C run-time 
library. These routines provide generic sorting and searching func- 
tions that you can use readily within your Turbo C programs. 

You might wonder, if Borland can develop generic sorting and 
searching routines, why is it not possible for you to do so. The answer is 
that you can. The difficulty becomes doing so in a manner that is still 
readily understandable. 

Because you are already conversant with the seatien tial search, it 
will be used as a test case. However, remember that the following 
code uses a significant number of pointers, casts, and redirections. 

As before, you must define functions to compare two values. In this 
case, you will be searching an array of type int and one of type float. 


int_cmp (int *x, int *y) 


if (*x == *y) 
return (1); 
else 
return (0); 
} 


flt_cmp (float *x, float *y) 


if (*x == *y) 
return (1); 
else 
return (0); 
} 


Next, you must define the routine that will perform the actual search: 


int generic_seq_ search (void *value, void *values, 
int num_elements, int width, 
-int (*compare) (void *, void *)) 
{ 


int i, location = -1; 


for (i = 0; (i < num_elements - 1) && location == -1; i++) 
if ((*compare) (value, (void *) ((char *) values + (i*width)))) 
location = i; 


return (location); 
} 
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Note that both the desired value and the array are defined as void 
pointers. Here is where the routine lays its generic foundation. 
The next confusing fragment is the actual comparison. 


if ((*compare) (value, (void *)((char *) values + (i*width)))) 


Since you are dealing with pointers, you are yet to be concerned with 
the array type. The goal in the comparison is to pass the address of the 
desired value along with the address of the current array element. The 
routine that performs the comparison is the only code fragment con- 
cerned with the array type. For example, the routine int__cmp simply 
uses the addresses it receives as pointers to the type int. Since this was 
the original goal, the routines work as desired. 

This program passes arrays of type int and float to the search 
routine. Note that the desired value must be passed by address: 


main () 
{ 
int flt_cmp (float *, float *); 
int. int -cmp. (int *, int: *)% 


int int _values[10]; 
float float_values[10]; 


int int _value = 2; 
float float_value = 2.0; 


int i; 


for (i = 0; i < 10; i++) 
{ 
int_values[i] = 
float _values[i} 


} 


i * 1; 
=i * 1.0; 


printf ("int result %d\n", 
generic seq search (&int_ value, int_values, 10, 
sizeof(int), int_cmp)); 


printf ("float result %d\n", 
generic seq search (&float_value, float_values, 10, 
sizeof(float), flt_cmp)); 
| 


Admittedly, this code is generic. Its difficulty lies in its readability. You 
can apply this concept to all of the routines in this chapter. This is how 
the searching and sorting routines in the Turbo C run-time library 
work. 

Selecting the proper sorting and searching algorithm has a definite 
impact on the execution time of your routines. Compilers that providea 
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sorting routine often use the quick sort. If you experiment with each © 
routine using arrays of 30, 300, and 3000 elements, you should find that 
for 30 elements, the execution time of each routine is almost the same; 
that the bubble sort is much slower than the other sorts for 300 ele- 
ments; and that the quick sort is much faster than the others for an 
array of 3000 elements. However, you also will find that the recursive 
nature of the quick sort makes it slower for smaller lists. 

Each sorting routine has attributes that make it more efficient for a 
specific application. You will find that you can increase the speed of 
your sorts by examining the number of elements in the array and 
invoking the sort that is best suited to the application. 


Input/Output 
Routines 


Probably the most important aspect of any computer program is its 
user interface. Good programs are too often under-utilized simply 
because users find them awkward. Unless your programs are easy to 
use, they will be of little use to others. 

Everyone in the computer industry has a definition of “user 
friendly.” To many, “user friendly” means a mouse-driven applica- 
tion. However, to most programmers, the command line is more than 
adequate to make a program user friendly. Writing user-friendly 
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programs depends to a great extent on the target audience. A pro- 
gram that is designed for an advanced user to operate from the 
command line will be terribly frightening to a novice. A mouse- 
- driven system can have tremendous overhead, which frustrates 
advanced users. Perhaps a more suitable goal is to make your pro- 
grams “user consistent.” A good program should make the user’s 
next response obvious. 
For example, assume that you need the user to enter a mailing 
address, as follows: 


Name: 
Address: | 
City: State: Zip: 


Some programs will prompt the user a line at a time, as shown here: 


Enter name: Kevin Shafer 


Enter address: 


To minimize surprising the user (and to help put the user at ease), a 
program should first display all of the prompts to which the user 
must respond: 


Name: 


Address: 


Criey: 


Next, the user can begin filling in the fields, as shown here: 
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Name: Kevin Shafer 


Address: 


Citys 


This allows the user to build a mental image of the screen and to 
have a good concept as to what comes next. 

If you use the routines presented in this chapter, developing user- 
consistent programs will be much easier. Rather than forcing you to 
worry about input/output (I/O) processing when you develop your 
programs, these routines enable you to concentrate on the task at 
hand. Most experienced programmers will testify that they spend 
the majority of their time strictly on I/O processing. The goal of this 
chapter is to develop powerful I/O routines once, and then to use 
them many times in the future. 


Output Routines 


The first collection of routines performs output operations. These 
routines output strings, integer values, and floating-point values. 
You do not use printf in these routines because of its slow speed and 
limited capabilities. 

Since the routines presented in this chapter are based on the rou- 
tine write__char_and_—attr from Chapter 7, they bypass Turbo C’s 
output routines and directly access the BIOS services. This enables 
you to control your own output. More important, by using write— 
char__and_—attr, your programs can easily specify the display attri- 
butes of each character on the screen display. Each of the routines in 
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this chapter allows you to specify the video display page that is cur- 
rently active. Most of you will always use display page 0. However, 
advanced programs often write output to one display page and then 
select that page as active (by using routines from Chapter 7). In so 
doing, the output appears instantaneously. 

The IBM PC and PC compatibles allow you to define the display 
attribute of every character on the screen. Display attributes 
include color, boldness, and even blinking. Each character displayed 
on the screen has an 8-bit attribute byte associated with it. Table 
12-1 defines the function of each bit in the attribute byte. 

The following program displays each of the attribute values by 
showing the number of the attribute that uses the attribute value. 
Use this program to help you select desirable attributes for your 
programs. | 


#include <stdio.h> 
main () 
Char str[4]; 
int attr, i; 
for (attr = 0; attr <= 255; attr++) 
Te eakeen (attr, str); 
for (i = 0; str[i]; i++) 
Pee er ere (0, 10, 39 + i); 
write char and attr (0, str[i], attr, 1); 


} 
getchar (); 
} 


The routine put__string enables you to specify the screen row and 
column location, along with the display attributes for a given string. 


main () 
{ 
int page = 0, row = 10, column = 10, attribute = 7; 


put_string ("User Prompt:", page, row, column, attribute, 80); 


} 
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Table 12-1. Functions of Bits in Attribute Byte 


Bit Color 


Blue foreground 
Green foreground 
Red foreground 
Bold 

Blue background 
Green background 
Red background 
Blinking 


Noor wondr © 


By using your previously developed library of routines, put—string 
is quite straightforward. 


char «str = “TEST”: 
int page = 0; 


int row = 0; 

put__string 
int column = 0; 

int attribute = 7; 


int length = 4; 


/* 

* void put_string (string, page, row, column, attribute, length) 
* 

* Output a character string at the row and column specified. 

* 

* string (in): String to be displayed. 

* page (in): Desired video display page. 

* row (in): Screen row to write the string at. 

* column (in): Screen column to write the string at. 

* 


attribute (in): Video display attribute for the string. 
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* 
* 
* 
* 
* 


length (in): Maximum number of characters to display. 


put_string ("User Prompt:", 0, 10, 10, 7, 11); 


void put_string (char *str, int page, int row, 


{ 


int column, int attribute, int length) 


int count = 0; 
void write char and attr (int, int, int, int); 
void set_cursor position (int, int, int); 


while ((*str) && (count < length)) 


{ 
set_cursor position (page, row, column + countt++t); 
write char and attr (page, *strt++, attribute, 1); 
} 


The routine put__centered__string enables you to output a char- 


acter string centered on the specified row. The routine is based on 
an 80-column screen display. 


+ + F & & HF FH HF HF HK FF KF HF OF 


EERE RSET DEEEEESS, 
char «string = “Turbo”; 
int page = 0; , Turbo 
int row = 10: put__centered__string 
int attribute = 7; | 


void put_centered_ string (string, page, row, attribute) 

Center a character string on the screen row specified. 

string (in): Character string to be displayed centered. 

page (in): Desired video display page. 

row (in): Desired screen row position for the string. 
attribute (in): Desired display attribute. 

put_centered_ string ("Turbo C Programmer’s Library", 0, 5, 7); 


This routine assumes an 80 column screen display. 
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void put_centered_ string (char *str, int page, 
int row, int attribute) 
{ 


int count = 0; 
int column; 


void write char_and_ attr (int, int, int, int); 
void set_cursor position (int, int, int); 


while (*(str + count) ) 
count++; 


column = 39 - (count / 2); 
while (*str) 
set_cursor position (page, row, columntt); 


write char and attr (page, *str++, attribute, 1); 
} 


The routine put—int enables you to output an integer value at a 
specific row and column location. As before, this routine also enables 
you to specify the display attribute and desired video page. 


int value = 77; 


Ce nN 
int page = 0; 
int row = 10; : v7 
put—int 
int column = 10; 
Pra aree e IT, 


int attribute = 7; 


int length = 5; 


/* 

* void put_int (value, page, row, column, attribute, length) 
* 

* Output an integer value at the row and column specified. 
* 

* value (in): Integer value to be displayed. 

* page (in): Desired video display page. 

* row (in): Screen row to write the string at. 

* column (in): Screen column to write the string at. 

* attribute (in): Video display attribute for the string. 
* 


length (in): Maximum number of characters to display. 
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* 


* put. ants (12945), 0, 10; 105. 74/21) s* 
x 
x / 


void put _int (int value, int page, int row, 
int column, int attribute, int length) 
{ 


int count = 0; 


void write char _and_attr (int, int, int, int); 
void set_cursor position (int, int, int); 


char str[(132]; 
int to ascii (value, eins 
while ((str[count]) && (count < length) ) 
set_cursor position (page, row, column + count); 


write char and attr (page, str[count++], attribute, 1); 


} 


The routine put—float places a floating-point value anywhere on — 
the screen. The field-length specifier enables you to suppress the 
display of insignificant digits (values of type float have seven digits 
of significance). 


float value = 77.66; 
int page = 0; 


int row = 10; 


int column = 10; put__float 
int attribute = 7; 


int length = 10; 


—— 


int num__elements = 3;—> 


void put_float: (value, page, row, column, attribute, 
length, num decimals) 


+ + + + + 


Output a floating point value at the row and column specified. 
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* value (in): Floating point value to be displayed. 

* page (in): Desired video display page. 

* row (in): Screen row to write the string at. 

* column (in): Screen column to write the string at. 

* attribute (in): Video display attribute for the string. 
* length (in): Maximum number of characters to display. 

* num_decimals (in): Maximum number of digits to the right of 
* the decimal point. 

* 

* put_float (12345.67, 0, 10, 10, 7, 11, 2); 

* 

*/ 


void put_float (float value, int page, int row, 
int column, int attribute, int length, 
int num_decimals) 


int count = 0; 


void write char and attr (int, int, int, int); 
void set_cursor position (int, int, int); 


char *str; 

int sign, decimal position; 

char *ecvt (double, int, int *, int *); 

str = ecvt ((double) value, length, &decimal_position, &sign); 


while ((str[count]) && (count < length) ) 
{ 
set_cursor position (page, row, column + count); 
if (count == decimal position) 


write char_and attr (page, ’.’, attribute, 1); 
counttt+; 


} 


else 
write _char_and attr (page, str[count++], attribute, 1); 


if (count > (num_decimals + decimal_position) ) 
break; 


The routine put—_prompt enables you to output prompt text to the 
screen in a manner similar to put__string. Unlike put—string, put— 
prompt displays the text and then removes any other characters 
remaining on that line. Thus, you must not worry about the previous 
screen contents when you display your prompt. 
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+ + +  F + HF F HK FE HK KF HK KF HK OF 


vo 


{ 


char «prompt = “Name:”; 


SEE DC RES, 
int page = 0; 
int row = 10; , 
ut_prom 
int column = 10; P 
EE 


int attribute = 7; 
int length = 10; 


void put prompt (prompt, page, row, column, attribute, length) 


Output a prompt at the row and column specified. Clear the 
text remaining on the line following the prompt. 


prompt (in): Prompt to be displayed. 

page (in): Desired video display page. 

row (in): Screen row to write the string at. 

column (in): Screen column to write the string at. 
attribute (in): Video display attribute for the string. 
length (in): Maximum number of characters to display. 


put_prompt ("Enter Name:", 0, 10, 10, 7, 15); 
/ 


id put_prompt (char *str, int page, int row, 
int column, int attribute, int length) 


int count = 0; 
void write char _and_attr (int, int, int, int); 
void set_cursor position (int, int, int); ‘ 


while ((*str) && (count < length) ) 
{ 


set_cursor position (page, row, column + countt++); 
write char and attr (page, *strt++, attribute, 1); 
} 


/* clear characters remaining on the line */ 
column += count; 


while (column < 80) 
{ . 

set cursor position (page, row, ++column) ; 

write char and attr (page, 0, 0, 1); 


} 
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Input Routines 


The next collection of routines enables you to get a character string, 
integer value, or floating-point value from the user in a controlled 
manner. Each of the routines presented in this section is based on 
the routine get_string. 

Many C programs often prompt a user to enter data that is 
stored internally as a character string. Because C programs use 
strings so frequently, a powerful function that enables you to control 
string input can be quite convenient. 

The following routine provides several significant features. It 
enables you to specify the screen location and maximum number of 
characters in the string. 

The routine allows you to provide a default string for the user to 
either select or edit. For example, if you are developing a mailing- 
list program and the most frequently used state is AZ, the user 
should not have to type in these letters with each new entry. Instead, 
you provide the letters “AZ” as the default. 

Because you can provide a default string, the user should be able 
to edit it. The routine get__string enables you to use the right arrow 
and left arrow keys, the BACKSPACE key, and the INS key to insert 
text. Because all of the routines in this section have been based on 
get_string, each routine provides all of these editing capabilities. 


char «string = “Default”; 
int page = 0; 


int row = 0; 


int attribute = 7; 


int highlight = 64; 
int length = 10; 
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get_string (string, page, row, column, attribute, 
high light, length); 


Display a default string to the user allowing the user to 
edit the string as desired. 


String (in): Default string which once edited becomes result. 

page (in): Desired video display page. 

row (in): Screen row to input the string at. 

column (in): Screen column to input the string at. 

attribute (in): Display attribute of the string. 

high light (in): Display attribute of the blank space remaining 
in the input field. 

length (in): Maximum number of characters in the input field. 


* + * + + HF FF HF F HF HK F HF HK OF KF K OF 


get_string (string, 0, 10, 10, 7, 65, 10); 
j | 


void get_string (char *str, int page, int row, 
int column, int attribute, 
int high light, int length) 


void write _char_and attr (int, int, int, int); 
void set_cursor position (int, int, int); 

int no_echo read (void); 

int get_shift state (void); 


int i, count = 0, done = 0, letter, scan_code; 


/* display the default string */ 
while ((str[count]) && (count < length) ) 
{ 


set_cursor position (page, row, column + count); 
write char _and_attr (page, str[count++], attribute, 1); 
} 


set_cursor position (page, row, column + count); 


if (length - count) 
write char and attr (page, 32, high _light, length - count); 


count = 0; 
set_cursor position (page, row, column + count); 


while (! done) 
{ 
letter = no_echo_read (); /* get the keystroke */ 


switch (letter) { 
case 8: /* back space */ 
if (count > 0) /* no characters to delete */ 


{ 
if (count + 1 == length) 
{ 


if (str{count]}) 
str({count] = ’\0'; 
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else 
set_cursor position (page, row, column + ~--count); 


str[{count] = ’\0’; 


write char _ and attr (page, 32, high_light, 1); 


break; 
} 
else /* shift all following char down */ 
{ 
for (i = --count + 1; i < length; i++) 
str[{i-1]) = str[il; 
i = 0; 


while ((strf{i]) && (i < length) ) 
{ 
set_cursor position (page, row, column + i); 
write char and attr (page, str[it++], attribute, 1 
, . 


set_cursor position (page, row, column + i); 


if (length > i) 
write char _ and attr (page, 32, high_light, 
length - i); 


set_cursor position (page, row, column + count); 
} 
} 


break; 


case 13: /* carriage return */ 
done = 1; 
break; 


case 0: scan _code = no_echo read (); 
if (scan_code == 77) /* right arrow */ 
{ 
if ((str[count]) && ((count + 1) != length) ) 
{ 


write _char_and attr (page, str[count++], attribute, 
set cursor position (page, row, column + count); 
} 
} 
else if (scan_code == 75) /* left arrow */ 
if (count) 
set_cursor position (page, row, column + --count); 


break; 


default: if (get shift state () & 128) 
{ 


for (i = length -1; i > count; i--) 
str{i] = str[i-1]; 


for (i = countt+l; i < length; i++) 
if (str[i]) 
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{ 
set_cursor position (page, row, column + i); 
write char and attr (page, str{i], attribute, 
} 
else 
break; 


set_cursor position (page, row, column+count) ; 


} 


str[count] = letter; 
write char and attr (page, letter, attribute, 1); 
if (count + 1 != length) 
set_cursor position (page, row, column + ++count); 


break; 
} 
} 


for (i = 0; str[i] && (i < length); i++) 
count++; 


Sstr[count] = ’\0’; 


The routine get__int enables you to get an integer value from the 
user at any location on the screen. This routine uses the routines 
ascli_to—int and int__to__ascli (presented previously in this text). 
This code implements get—int: 


int value = U7; 
int page = 0; 


int row = 10; 


int column = 10; get_int 
int attribute = 7; 
int highlight = 65; 


int length = 10; — 


Integer value entered 


/* 

* get_int (value, page, row, column, aber SDRC! 

x high light, length); 

* 

* Display a integer value to the user aatowsng the user to 
* 


edit the value as cestned: 
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* 

* value (in): Default value which once edited becomes result. 

* page (in): Desired video display page. 

* row (in): Screen row to input the value at. 

* column (in): Screen column to input the value at. 

* attribute (in): Display attribute of the value. 

* high light (in): Display attribute of the blank space remaining 
* in the input field. 

* length (in): Maximum number of characters in the input field. 
* 

* result = get_int (12345, 0, 10, 10, 7, 65, 10); 

* 

af 


get_int (int value, int page, int row, int column, 
int attribute, int high light, int length) 
{ 


void get string (char *, int, int, int, int, int, int); 
char str[132]; 


int done = 0; 
int status; 


while (! done) 
{ 
int _to_ascii (value, str); 
get_string (str, page, row, column, attribute, 
high light, length); 


status = ascii_to_ int (str, &value); 


if (status != -1) 
done = 1; 
} 


return (value); 
} 

The routine get—float allows you to get a floating-point value 
from the user. The routine requires the routine ascii__to—float, 
which converts an ASCII representation of a floating-point value to 
a numeric value, as shown here: 


Char «str = “88.77”; 
float result; 


ascii__to__float 


0 if routine is successful 
—1 if a conversion error occurred 
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ascii _ to float (string, result) 


Convert an ASCII representation of a floating point value 
to its numeric equivalent. 


string (in): String to convert. 
result (out): Floating point result. 


status = ascii_to float ("123.333", &result); 
If successful, ascii_to float returns the value 0. 


f 
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ascii to float (char *str, float *result) 
int count, sign = 1; 
double powl10 (int) ; 


*result = 0.0; 


while (*str ==’ ") 
Strt+t; 

if ((*str == '-"’) || (*str == '+/)) 
Sign = (*strt+ == '-') 2? -1: 1; 


while (*str) 
if ((*str >= '0’) && (*str <= '9')) 
*result = *result * 10.0 + (*Strt++ - '0’); 
else if (*strt++ == ’.') 
break ; 
else 
. return (-1); 


if (*str) 
for (count = 1; *str; ++count, ++str) 
if ((*str >= '0’) && (*str <= '9’)) 
*result = *result + ((*str - '0') / powl0(count)); 
else . 
return (-1); 


*result = *result * sign; 


return (0); 
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This routine implements get—float: 
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float value = 88.77; 
int page = 0; 


int row = 10; 


int column = 10; 


int attribute = 7; 


get__float 


int highlight = 65; —am 


int length = 10; — 


Floating-point value entered 


get_float (value, page, row, column, attribute, 
high light, length); 


Display a floating point value to the user allowing the user to 
edit the value as desired. 


value (in): Default value. 

page (in): Desired video display page. 

row (in): Screen row to input the value at. 

column (in): Screen column to input the value at. 

attribute (in): Display attribute of the value. 

high light (in): Display attribute of the blank space remaining 
in the input field. 

length. (in): Maximum number of characters in the input field. 


result = get float (12345.67, 0, 10, 10, 7, 65, 10); 


float get float (float value, int page, int row, int column, 


int attribute, int high light, int length) 
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void get_string (char *, int, int, int, int, int, int) ; 
char *ecvt (double, int, int *, int *); 

int ascii _to_ float (char *, float *); 

char *str; 

int done = 0, decimal pt, sign; 

int status, i, len; 


while (! done) 
{ 


str = ecvt ((double) value, lengtht1l, &decimal pt, &sign); 


for (len = 0; strf{len]; lent+) ; 


for (i = len; i > decimal pt; i--) 
str[i] = str[i - 1]; 


str[{decimal pt] = ’.'; 
if (sign) 
{ 


for (i = lentl; i > 0; i--) 
str[i] = str[{i - 1]; 


str [0]. = /="3 
} 


get_string (str, page, row, column, attribute, 
high light, length); 


Status = ascii_to_float (str, &é&value); 


if (status != -1) 
done = 1; 
} 


return (value); 


User-Consistent I/O 


Programs should provide a constant interface that minimizes the 
possibility of user surprise (or confusion). Consider the previous 
example of the mailing-list program: 


Name: 


cera 


Address: 


City: 
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You can produce code to obtain this information from the user, as 
shown here: 


main () 
{ 


void put_string (char *, int, int, int, int, int); 
put_string ("Name:", 0, 1, 10, 1, 10); 

put_string ("Address:", 0, 3, 10, 1, 10); 
put_string ("City:", 0, 5, 10, 1, 10); 

put_string ("State:", 0, 5, 30, 1, 10); 
put_string ("Zip:", 0, 5, 50, 1, 10); 


Although this program is much improved over a one-line-at-a- 
time interface discussed at the beginning of this chapter, you can 
make it even better. First, the program should make the current 
prompt (such as Name:) distinct from other prompts by changing 
the display attribute of the current prompt. The program should 
display a single line of explanatory text at the bottom of the screen, 
as shown here: 


Name: 


Address: 


City: 


Enter your full name (Example: Tom Burns) 


Once the user enters the data required for that entry, the prompt 
attribute should reset and the descriptive (or help text) should 
disappear. | 

The following routines are basically all-in-one routines that allow 
you to prompt the user for a string, integer, or floating-point value. 
These routines enable you to specify the following: 
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¢ PROMPT (such as Name:)— Row, Column, Attribute 


e Input/Output value (such as namestr)—Row, Column, 
Attribute 


¢« Help or Descriptive text —Row, Column, Attribute 


Before examining these routines, consider a possible invocation of 
get__prompted_—string. 


char str{132] = "Tom Burns"; 


get_prompted string (str, 0, 10, 20, 30, 7, 64, “Enter Name:", 
, 10, 7, 13, “Enter your name.", 23, 7, 
40, 7); 


Upon invocation, this program displays the following: 


Enter Name: Tom Burns 


Enter your name. 


The following helps you to relate the parameters of get 
prompted_string to the actual display output: 


Enter Name: Tom Burns 
aes” —_ 
Prompt Default string 


Enter your iiame. 


\\—— 
Description help text 


This routine implements get_prompted—string: 


Char «str = “Default”: 

int page = 0; 

int str_row = 10; 

int str_column = 20; 

int str_length = 10; 

int attribute = 7; 

int highlight = 65; 

char «prompt = “Enter Name”; 
int prompt__row = 10; 

int prompt—column = 10; 

int prompt—length = 10; 

char *desc = “Enter your name.”; 
int desc_row = 23; 

int desc_column = 10; 

int desc_length = 30; 


int normal_attribute = 0; 


+ + + + & & + H HF HF HK HF HK HF HK OK HF FF OH OF OF KF OF OF 


INPUT/OUTPUT ROUTINES 


get_prompted__string 


void get_prompted_ string (str, page, str_row, str_column, 
str_length, attribute, high_light, prompt, prompt_row, 
prompt_column, prompt_length, desc, desc_row, desc column, 
desc_length, normal attribute) 


Prompt the user for a character string providing a default 
for editing purposes. Display help text as specified which 
is erased from the screen once the data entry is complete. 


str (in/out): Default string which once edited becomes result. 


page (in): Desired video display page. 

Str_row (in): Screen row for string display. 

str column (in): Screen column for string display. 

Str length (in): Maximum number of characters in the string. 
attribute (in): Display attribute of string. 

high light (in): Display attribute of empty field space. 
prompt (in): Desired user prompt. 

prompt row (in): Screen row for user prompt. 

prompt _column (in): Screen column for user prompt. 
prompt_length (in): Maximum number of characters in prompt. 
desc (in): Help text. 

desc_row (in): Screen row of the help text. 

desc column (in): Screen column of the help text. 
desc_length (in): Maximum number of characters in help text. 
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* normal attribute (in): Current background color attribute. 
* ; 


* get_prompted_ string (str, 0, 10, 20, 30, 7, 64, “Enter Name:", 
* 


10, 7, 13, “Enter your first name.", 23, 7, 40, 7);- 


* 


*/ 


void get_prompted_ string (char *str, int page, int str_row, 


{ 


} 


int str_column, int str_length, int attribute, int high_light, 

char *prompt, int prompt _row, int prompt_column, int prompt_length, 
char *desc, int desc_row, int desc_column, int desc_length, 

int normal_ attribute) 


void get_string (char *, int, int, int, int, int, int); 
void put _ string (char x -int, int, int, int, int); 
void put_ prompt (char x, int, int, int, int, int); 


put_prompt (prompt, page, prompt_row, prompt_column, 
high light, prompt_ length) ; 


put_string (desc, page, desc_row, desc column, high light, 
desc_length); 


get_string (str, page, str_row, str_column, attribute, 
high light, str. length) ; 


put string (prompt, page, prompt_row, prompt_ column, 
normal _attribute, prompt _ length) ; 


put_string (desc, page, desc_row, desc_column, 0, desc_length); 


This routine implements get_prompted__int: 


int ‘default = 5; 

int page= 0; 

int row = 10; 

int column = 20; 

int length = 10; 

int attribute = 7; 

int highlight = 65; 

char «prompt = “Enter age” 
int prompt—rom = 20; 


get__prompted__string 


int prompt—column = 1; 

int prompt length = 7; 

char «desc = “Type in your age” 
char desc__row = 23; 

char desc.__column = 5; 

int normal_attribute = 0; 


‘int value entered 
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int get_prompted_ int (value, page, row, column, 
length, attribute, high_light, prompt, prompt_row, 
prompt_column, prompt_ length, desc, desc_row, desc_column, 
desc_length, normal attribute) 


Prompt the user for an integer value providing a default 
for editing purposes. Display help text as specified which 
is erased from the screen once the data entry is complete. 


value (in): Default value for editing. 

page (in): Desired video display page. 

row (in): Screen row for value display. 

column (in): Screen column for value display. 

length (in): Maximum number of characters in the value. 
attribute (in): Display attribute of string. 

high_light (in): Display attribute of empty field space. 
prompt (in): Desired user prompt. 

prompt _row (in): Screen row for user prompt. 

prompt _column (in): Screen column for user prompt. 

prompt _ length (in): Maximum number of characters in prompt. 
desc (in): Help text. 

desc_row (in): Screen row of the help text. 

desc _column (in): Screen column of the help text. 
desc_length (in): Maximum number of characters in help text. 
normal _ attribute (in): Current background color attribute. 


age = get_prompted int (27, 0, 10, 20, 30, 7, 64, “Enter Age:", 
0, 7, 13,"Enter age and press Enter.", 23, 7, 40, 7); 


/ 


int get_prompted_ int (int value, int page, int row, 


int column, int length, int attribute, int high_ light, 

char *prompt, int prompt_row, int prompt_column, 

int prompt_length, char *desc, int desc_row, int desc_column, 
int desc_length, int normal_attribute) 


void get_ string (char *, int, int, int, int, int, int); 
void put_string (char *, int, int, int, int, int); 
void put_prompt (char *, int, int, int, int, int); 


int get_int (int, int, int, int, int, int, int); 


_ put_prompt (prompt, page, prompt_row, prompt_ column, 


} 


high_light, prompt_length) ; 


put_string (desc, page, desc_row, desc_column, high_light, 
desc_length) ; 


value = get_int (value, page, row, column, attribute, 
high __ light, length) ; 


put_string (prompt, page, prompt_row, prompt_column, 
normal_attribute, prompt_length) ; 


put_string (desc, page, desc_row, desc_column, 0, desc_length) ; 


return (value) ; 
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The routine get__prompted_float allows you to obtain a floating- 
point value from the user, as shown here: 
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float value; 
value = get prompted float (45000.00, 0, 10, 20, 10, 14, 64, 


"Enter Salary:", 10, 5, 13, “Enter your current salary.", 
23, 7, 40, 7); 


Upon invocation, this program will display the following: 


Enter Salary: 45000.00 


Enter your current salary. 


This code implements get__prompted—float: 


float default = 5.50; 
int page = 0; 

int row = 10; 

int column = 20; 

int length = 10; 

int attribute = 7; 
int highlight = 65; 
char «prompt = “Enter Cost”; get__prompted__float 
int prompt—row = 20; 

int prompt—column = 1; 

int prompt_iength = 10; 

char «desc = “Type in amount”; 
char desc_row = 23; 

char desc__column = 5; 

int normal_attribute = 0; 


Float value entered 
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float get_prompted_ float (value, page, row, column, 
length, attribute, high_light, prompt, prompt_row, 
prompt_column, prompt_length, desc, desc_row, desc_column, 
desc_length, normal_attribute) 


Prompt the user for a floating point value providing a default 
for editing purposes. Display help text as specified which 
is erased from the screen once the data entry is complete. 


value (in): Default value for editing. 

page (in): Desired video display page. 

row (in): Screen row for value display. 

column (in): Screen column for value display. 

length (in): Maximum number of characters in the value. 
attribute (in): Display attribute of string. 

high light (in): Display attribute of empty field space. 
prompt (in): Desired user prompt. 

prompt _row (in): Screen row for user prompt. 

prompt _column (in): Screen column for user prompt. 

prompt length (in): Maximum number of characters in prompt. 
desc (in): Help text. 

desc_row (in): Screen row of the help text. 

desc _column (in): Screen column of the help text. 
desc_length (in): Maximum number of characters in help text. 
normal attribute (in): Current background color attribute. 


salary = get_prompted float (27, 0, 10, 20, 30, 7, 64, 
"Enter Salary:", 10, 7, 13,"“Enter your current salary.", 
23; T, 40, 7) 
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float get_prompted float (float value, int page, int row, 
int column, int length, int attribute, int high_light, 
char *prompt, int prompt_row, int prompt_column, int prompt_length 
char *desc, int desc_row, int desc_column, int desc_length, 
int normal attribute) 


void get_string (char *, int, int, int, int, int, int); 
void put string (char *, int, int, int, int, int); 
void put prompt (char *, int, int, int, int, int); 
float get float (float, int, int, int, int, int, int); 


put _prompt (prompt, page, prompt _row, prompt_column, 
high light, prompt _length) ; 


put_string (desc, page, desc_row, desc_column, high_light, 
desc_length); 


value = get_float (value, page, row, column, attribute, 
high light, length); 


put_string (prompt, page, prompt_row, prompt_column, 
normal attribute, prompt _length); 


put_string (desc, page, desc_row, desc column, 0, desc_length); 


return (value) ; 
} 
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Probably the most important collection of routines that you can 
place into a library are those that perform I/O. Build on the routines 
presented in this chapter and your I/O processing should become 
much easier. | 


Dynamic Memory 


Chapter 10 examined arrays and the manipulation of arrays within 
Turbo C. Chapter 11 extended array manipulation to sorting and 
searching operations. Although you can often use arrays effectively 
within most applications, many instances occur where fixed array 
sizes cause programs to be restrictive. 

Consider this example. A program tracks account balances for 
100 clients by using the arrays shown here: 


main () 
int employee id [100]; 
float account_balances [100]; 
float accounts rec [100]; 


/* program code here */ 
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Each time the program must update an account balance, it searches 
the array customer__id for the corresponding customer index. Once 
it finds the array, the program uses the index to update the accounts 
receivable array. Although this algorithm seems effective, it encoun- 
ters problems when it gets to customer 101. The arrays no longer 
provide adequate storage space. You must now modify the program. 

If you have based your array declarations and program loops on 
macro constants, 


main () 
int employee id [MAX CUSTOMER]; 
float account balances [MAX CUSTOMER]; 
float accounts rec [MAX CUSTOMER]; 


/* program code here */ 


you can modify a single statement in order to increase the size of 
your arrays. 


#define MAX CUSTOMER 150 


Although this simple change will successfully modify the pro- 
gram, the code must still be recompiled. This step is relatively easy 
if you are a programmer. However, if you have distributed the exe- 
cutable files to many end users, you must now build a new execut- 
able file each time customer bases change. 

A possible solution is to allocate a large amount of space for more 
array entries than could ever possibly exist, as shown here: 


#define MAX CUSTOMER 10000 


Although this solves one problem, it unfortunately creates several 
additional ones. In this case, you have wasted considerable memory 
on empty array elements. If you have multiple arrays that must be 
maintained, you will soon run out of memory. 
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Dynamic variables provide a data structure that can actually 
grow or shrink by itself as your needs require. This reduces wasted 
memory space and prevents a program’s storage requirements from 
being restricted. If you place elements into the dynamic lists in a 
specific manner, you can greatly reduce the number of sorting and 
searching algorithms that you may later have to perform. This chap- 
ter presents several algorithms that are commonly used in dynamic- 
list manipulation. Although in most cases you must modify these 
routines to suit your specific needs, the routines will provide a foun- 
dation on which you can build. 


Dynamic Lists 


Each time you use arrays, you must specify the storage require- 
ments during program development. The array declaration 


int values[10]; 


creates an array with space for ten values, as shown here: 


values [0] 
values [1] 
values [2] 
values [3] 
values [4] 
values [5] 
values [6] 
values [7] 
values [8] 
values [9] 
values 
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A dynamic list starts with a single element called a node. This 
element serves as the start (or head) of the list, as shown here: 


Value 


Pointer 


Start 


As you place values into the list, you simply create and connect addi- 
tional nodes; as shown here: 


[wae] [Cvawe] [vane 
[Pointer -—>{_Pointer _}—={ Pointer 


Start 


If an element in the list goes away (is no longer needed), you shrink 
the list, as shown next: uw 
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Start 


Start 


Pointer 


Value 


To create a linked list, you must first define a structure that pro- 
vides storage space not only for the value to store, but also for a 
pointer to the next entry in the list. If you want to store customer 
account balances, your structure might contain the following: 


struct 
char 
char 
char 
char 
char 
char 


customers { 
name [32]; 
phone[11]; 
address[32]; 
City {15} 
State [3]; 
zip[(10]; 


float balance; 
struct customers *next; 


e 
a 


Note that the pointer within the structure is a pointer to a struc- 
ture of the same type. This should make sense because all of the 
elements in the list are the same. A structure containing a pointer 
that points to a structure of the same type is called a self-referential 


structure. 


To use a linked list, you normally perform the following steps: 
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1. Define a structure to contain the desired values and pointer to 
the next node in the list. 


2. Create the first node in the list by allocating memory through 
the use of calloc or malloc (Turbo C run-time library routines). 
Assign the memory to the first pointer in the list (called start 
or head). | 


3. Create nodes for the remaining entries, again by using calloc 
or malloc. Assign the pointer of each node to point to the next 
node in the list. The last node in the list should point to NULL. 


4. Use the list of entries as required. | 


5. Once the nodes are no longer required, use the routine free 
_ (Turbo C run-time library) to release allocated memory. 


The following program creates a linked list that contains the 
uppercase letters of the alphabet: 


If you follow the steps previously listed, your processing is as follows: 


1. Define a structure to contain the desired values and pointer to 
the next node in the list. 


struct list_entry { 
char letter; 
struct list _entry *next; 
} *start, *node, *next; 
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2. Create the first node in the list by allocating memory through 
the use of calloc or malloc (Turbo C run-time library routines). 
Assign the memory to the first pointer in the list (called start 
or head). 


if ((start = (struct list _entry *) 
calloc(l, sizeof(struct list _entry))) == NULL) 


{ 
printf ("Unable to allocate memory for the list\n"); 


exit (1); 


Note the type coercion of the type returned by the call to calloc. 


if ‘( (start. = (struct. list entry *) 
calloc(1, sizeof(struct list_entry))) == NULL) 


By default, calloc returns a pointer to the type void. Since the struc- 
ture is not type void, we will use the cast. Also note that if calloc 
cannot allocate the desired memory, it returns the value NULL. 


3. Create nodes for the remaining entries again by using calloc 
or malloc. Assign the pointer of each node to point to the next 
node in the list. The last node in the list should point to NULL. 


for (letter = /A’; letter <= 'Z'; letter++) 


if ((node->next = (struct list_entry *) 
calloc(1l, sizeof(struct list entry))) == NULL) 
= 
printf ("Unable to allocate memory for the list\n"); 
exit (1); 


node = node->next; 
node->letter = letter; 
node->next = NULL; 

} 
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Once you have created the list, you want to print out the values that 
it contains. This becomes step 4. 


4. Use the list of entries as required. 


for (node = start->next; node != NULL; node = node->next) 
printf ("$c\n", node->letter) ; 


- This loop begins by examining the first element in the list 
(pointed to by start). If that element exists, its value is displayed (the 
letter ”A”). Next, the loop assigns the current node to point to the 
next element in the list (the letter ”"B”). This process continues until 
you reach the letter "Z". Once "Z” is printed, the current node is 
assigned the value NULL, which is the ending condition. | 


5. Once the nodes are no longer required, use the routine free 
(Turbo C run-time library) to release allocated memory. 


for (node = start; node != NULL; node = next) 
; 


next = node->next; 
free (node); 
} 


To remove nodes from the list, you use the third pointer (next). 
Begin by assigning node to point to start, and next to point to 
node —>next. 
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Once this processing is finished, you can free the memory pointed to 
by node. 


The pointer node is now assigned the value contained in next, and 
next is assigned node—>next. This proces repeats until all of the 
memory has been released. 

Putting all of the pieces together, the complete program is as 
follows: 


#include <stdio.h> 
main () 
void *calloc (unsigned, unsigned) ; 
struct list_entry { 
Char letter; 
Struct list _entry *next; 
} *start, *node, *next; 


char letter; 


if ((start = (struct list_entry *) 
calloc(1, sizeof (struct list _entry))) == NULL) 
{ 


printf ("Unable to allocate memory for the list\n"); 
exit (1); 
} 
node .= start; 


for (letter = ’A’; letter <= 'Z’; letter++t+) 
{ 


if ((node->next = (struct list _entry *) 
calloc(1, sizeof(struct list entry))) == NULL) 
{ ; 


printf ("Unable to allocate memory for the list\n"); 
exit (1); 


354 TURBO C PROGRAMMER’S LIBRARY 


} 
node = node->next; 
node->letter = letter; 
node->next = NULL; 
} 


for (node = start->next; node != NULL; node = node->next) 
printf ("%c\n", node->letter); 


for (node = start; node != NULL; node = next) 
next = node->next; 


free (node); 


} 


In this example, the nodes contained simple data. However, you 


could have been creating a list of customer information, as shown 
here: | 


(Customer ID) 
(Balance) 


Although the structure is different, the steps required to create the 
list are the same. The structure in this case could be as follows: 


struct customers { 

char name[30]; 

char address[30]; 

char city[15]; 

char state[3]; 

char zip[11]; 

char phone[il]; 

float balance; 

struct customers *next; 
-} 3 
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Maintaining a Sorted List 


If you place items in your list in a specified manner, you can often 
reduce the amount of sorting you may later need to perform. For 
example, if you want to create a list of numbers entered by the user, 
and the user types these numbers, 


17 3 5 2 


you can build the list in sorted order, as shown here: 


In this case, use a routine called list_insert, which places an 
element into the list based upon the value in the member value: 


* 
* 
* 
* 
* 
x 


list_insert (value, start) 
Place a value into a linked list in sorted order. 


value (in): Value to add to the list. 
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: Start (in): First node in the list. 

* status = list_insert (5, start) ; 

* If list_insert cannot allocate the memory required, it returns 
* the value -l. If successful, this routine returns the value 0. 
+/ 


int list_insert (int value, struct list_entry *start) 
f 


struct list_entry *new_node, *node, *previous; 
void *calloc(unsigned, unsigned) ; 


node=start->next; 
previous = start; 


while ((node != NULL) && (node->value < value) ) 
{ . 

previous = node; 

node = node->next;_ 


} 


if ((new_node = (struct list_entry *) 
calloc(1, sizeof(struct list_entry))) == NULL) 
return (-1); 


new _node->value = value; 
new_node~>next = node; 
previous->next = new_node; 


return (0); 


Modifying the previous program slightly to use this routine, the code 
now becomes 


#include <stdio.h> 


struct list_entry { 
char value; 
struct list_entry *next; 
} ; 


main () 
{ 

void *calloc (unsigned, unsigned) ; 

struct list entry *start, *node, *next; 


char letter; 


if ((start = (struct list_entry *) 
calloc(1, sizeof(struct list_entry))) == NULL) 
{ : 


printf ("Unable to allocate memory for the list\n"); 
exit (1); 
} | . 
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node = start; 
node->next = NULL; 


for (letter = ’/A’; letter <= '2Z’; letter+t+) 


if (list_insert (letter, start) == -1) 
{ 
printf ("Unable to allocate memory for the list\n"); 
exit (1); 
} 
for (node = start->next; node != NULL; node = node->next) 


printf ("%c\n", node->value) ; 


for (node = start; node != NULL; node = next) 
{ 
next = node->next; 
free (node); 
} 


By using this routine, you can place ten integer values into the 
list, as shown here: 


#include <stdio.h> 


struct list_entry { 
int value; 
struct list_entry *next; 
3 


main () 
{ 


void *calloc (unsigned, unsigned) ; 
struct list_entry *start, *node, *next; 
int i, value; 


int get_prompted int (int, int, int, int, int, int, int, 
char *, int, int, int, char *, int, 
Int; int; Ant) 


if ((start = (struct list_entry *) 
calloc(1, sizeof(struct list_entry))) == NULL) 
{ ‘ 
printf ("Unable to allocate memory for the list\n"); 
exit (1); 
} 


node = start; 
node->next = NULL; 


for (i = 0; i < 10; i++) 
{ 
value = get_prompted int (0, 0, 10, 20, 30, 7, 64, “Value:", 
10, 7, 13,"Enter an integer then press Enter.", 23, 7, 40, 7); 


if (list_insert (value, start) == -1) 
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{ . 
printf ("Unable to allocate memory for the list\n"); 
exit (1); 

} 
} 


for (node = start->next; node != NULL; node = node->next) 
printf ("%d\n", node->value) ; 


for (node = start; node != NULL; node = next) 
next = node->next; 


free (node); 
} 


The routine works by tracking two nodes (the previous and current), 
as shown here: 


Previous Current 


As you traverse the list in search of the correct location at which 
to insert the value, you must update both pointers, as shown next: 
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| 


Value 


ae ag ees a es 


Start 


Previous Current 


Once you find the correct location, insert the value by using the two 
nodes, as illustrated here: 


Previous Current 
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Note the processing that is required to free the memory allocated by 
list. oe 


for (node = start; node != NULL; node = next) 
{ — 
next = node->next; 


free (node); 


} 
You can instead use the routine free__list, as illustrated here: 


void free list (start) 

Release memory previous allocated for a dynamic structure. 
start (in): First node in the list. 

Pree list. (stark); 


/ 


* FF HF OF 


void free list (struct list_entry *start) 
{ 


SErUCt -bistentry “node; <*next,- . 


for (node = start; node != NULL; node = next) 
{ 
next = node->next; 
free (node); 
} 
} 


Deleting an element from a linked list is similar to inserting a 
node into the list. You again use two nodes to track the previous and 
current nodes. Given the list, 
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the processing to delete the node containing the value 7 becomes as 
follows: 


362 
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The routine list__delete deletes a node from the linked list. 


Again, it is based upon the contents of the member value. If multi- 
ple nodes contain the same value, 


* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
x 
* 
* 


int list delete (int value, struct list_entry *start) 
{ 


list_delete (value, start) 
Remove a node containing the value specified from a linked list. 


value (in): Value to remove from the list. 
start (in): First node in the list. 


status = list delete (5, start); 


If list delete is successful, it returns the value 0, otherwise 
it returns the value -l. 


struct list entry *node, *previous; 


node=start->next; 
previous = start; 


while ((node != NULL) && (node->value 


{ 
previous = node; 
node = node->next; 
} 


if (node) 
{ 
previous->next = node->next; 
free (node); 
return: (0) 
} 
else 
return (-1); 


} 


Doubly Linked Lists 
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!= value) ) 


By now, you should understand that a linked list can provide consid- 
erable flexibility. The difficulty with linked lists at this point may be 
the processing required to insert and delete a node. You can create 
an even more flexible dynamic structure called a doubly linked list. 
Unlike a singly linked list (which only contains a pointer to the next 
element), a doubly linked list contains a pointer to the next and to 
the previous elements, as shown here: 


The structure now contains two pointers, as follows: 


struct double link { 
int value; 
struct double link *previous; 
struct double link *next; 
} 3 
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Since you now have a pointer to the previous and next elements in 
the list, you can eliminate the need for tracking two pointers during 
insert and delete operations. 


doubly list_insert (value, start) 
Insert a value in a doubly linked list in sorted order. 


value (in): Value to placed into the list. 
Start (in): First node in the list. 


status = doubly list_insert (5, start); 


rt doubly list insert is successful, it returns the value 0, 
otherwise, this routine returns the value -l. 


/ 


+ + + + + FF * HF K KF HF KF OF 


int doubly list _insert (int value, struct list_entry *start) 
eS , 
struct list_entry *new_node, *node; 
void *calloc(unsigned, unsigned) ; 


node=start->next; 
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/* locate insertion point */ 


while ((node != NULL) && (node->value < value) ) 
if (node->next != NULL) 
node = node->next; 
else 
break; 
if ((new node = (struct list entry *) 
~ cCalloc(1, sizeof(struct list _entry))) == NULL) 
return -(-1)% 


new node->value = value; 


if ((node != NULL) && (node->next != NULL)) /* not last entry */ 
{ , 
new_node->next = node; 
new node->previous = node->previous; 
(node->previous) ->next = new_node; 
node->previous = new_node; 


else /* first, last or next to last entry */ 
{ 
if ((start->next == node) && (node == NULL) ) 
{ 
new _node->previous = start; /* first list entry */ 


start->next = new_node; > 
new_node->next = NULL; 


} 
else if (value < node->value) /* next to last */ 


{ 

new_node->next = node; 
new_node->previous = node->previous; 
(node->previous) ->next = new_node; 


else 
{ /* last entry */ 
new _node->next = NULL; 
new _node->previous = node; 
node->next = new_node; 
} 
} 


return (0); /* successful insertion */ 


} 
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In a similar manner, this routine deletes an element from a dou- 
bly linked list. Once again, if two elements have the same value, only 


the first is deleted. 


/ 
doubly list delete (value, start) 


Remove a node containing a specified value ina doubly linked 
Lists 


+ + + + * 


a 
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value (in): Value to be removed. 
Start (in): First node in the list. 


status = doubly list_delete (5, start); 
If successful, this routine returns the value 0, otherwise it 
returns the value -1. If multiple occurrences of the value 


exist in the list, only the first is deleted. 


/ 


+ + + + +  F F HF OF 


int doubly list delete (int value, struct list_entry *start) 
{ 
Struct list entry *node; 
node=start-—>next; 


/* find the value */ 
while ((node != NULL) && (node->value != value) ) 
node = node->next; 


if (node) 
{ 


(node->previous) ->next = node->next; 
if (node->next != NULL) 
(node->next) ->previous = node->previous; 
free (node); 
return (0); 
} 
else 
return (-1); 
} 


Binary Trees 


Linked lists add considerable flexibility to your programs. By using 
a structure similar to that of a doubly linked list, 


struct binary tree { 
int value; 
struct binary tree *right; 
struct binary tree *left; 
} ; 


you can create a data structure in which all of the elements are 
automatically placed into a presorted order. When you later need to 
locate a value, you can do so with the same performance as that 
associated with a binary search. The new structure is called a 
binary tree. The structure appears as follows: | 
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Value 


Each time you add a value to the binary tree, you begin by exam- 
ining the first node (or root) of the tree. If the value is less than that 
of the root, you traverse the left side of the tree. If the value is 
greater than or equal to that of the root, you traverse the right side 
of the tree. Given the following numbers, 


os 5 172 9 8 


you would construct the tree as follows. The value 3 will be placed in 
the root node of the tree. 
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Likewise, the value 1 is less than 3, so it becomes a left node. 


bee es 
[NULL|NULL| 


Since 7 is greater than 3, you traverse the ont side of the tree. 
Since it is also greater than 5, it becomes a right node. 


a 


a ar 


Since 2 is less than 3 but greater than 1, it is ree in the tree, as 
shown next: 


DYNAMIC MEMORY 369 


NULL} NULL 


Bees 


Figure 13-1. Binary tree after adding values 8 and 9 
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To list the elements in the tree, follow similar steps. First, you 
begin at the root and traverse the left side of the tree. You traverse 
nodes to the left until no nodes remain. At that point you print the 
value of the current node, move up one node and print its value, and 
then begin traversing the right nodes, if they exist. Given the tree, 


you would display the values as shown in Figure 18-2. 
Likewise, given the tree, | 


— 


a 
ea rey 
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Value 7 is displayed 


Fugure 13-2. Values displayed while traversing nodes 


the values would be printed as shown in Figure 18-3. 
The following routine places a node into a binary tree: 
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ee 


ac 


| 


Value 5 is printed 


1 


Value 3 is printed 


Figure 13-3. Values printed from binary tree 
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as 


+ * FF FFF FF * FF 


tree _ insert (value, node) 
Place a value into a binary tree. 


value (in): Value to placed into the tree. 
node (in): Starting node in the "current" binary tree. 


Stelus = Cree insert (S;-node); 


If successful, tree insert returns the value 0, otherwise 
it returns the value -1. 


/ 
int tree insert (int value, struct list_entry *node) 
{ 


void *calloc(unsigned, unsigned) ; 


if (value < node->value) 


if (node->left != NULL) 
tree insert (value, node->left); 
else 
{ . 
L£ ((node->left = (struct list entry *) 
calloc(1, sizeof(struct list _entry))) == NULL) 
return (-1); 


(node->left)->right = NULL; 
(node->left)->left = NULL; 
(node->left)->value = value; 
} 
else 
if (node->right != NULL) 
tree insert (value, nodé->right); 


else 
lf ((node->right = (struct list_entry *) 
calloc(], sizeof (struct list entry))) == NULL) 
recurnm. (1) 7 


(node->right) ->right = NULL; 
(node->right) ->left = NULL; 
(node->right) ->value = value; 


} 


return *CO)}- 


} 


373 


Note that the routine is recursive. This is because of the recursive 
definition of a binary tree. If you consider each subtree as its own 


binary tree, your processing is identical at each node. 


In a similar manner, the following routine displays the conten 


of a binary tree by using the algorithm previously discussed: 
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x . 
. void show tree (node) 
‘i node (in): Start of the "current" binary tree. 
show tree (root); 
* You must change the printf control sequence based upon 
* the type of value to display. 
*/ 


void show_tree (struct list _entry *node) 


{ 
if (node->left) 
show tree (node->left); 


printf ("Sd\n", node->value) ; 
if (node->right) 


show_tree (node->right); 
} 


In a similar manner, the following routine releases memory pre- 
vously allocated for a binary tree: 


* 
. void free tree (node) 
: Release the memory previously allocated for a binary tree. 
* node (in): Starting node in the "current" node. 
* free. tree (root); 
: 


f 


void free tree (struct list entry *node) 


{ 
if (node->left) 
free tree (node->left); 


if (node->right) 
free tree (node->right) ; 


free (node); 
} 


Just as you must be able to insert items into the binary tree, you 
must also be able to delete them. Given the following tree, 
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a 


[3 


the processing to delete the node containing the value 7 requires two 
steps. First, you must assign the right pointer of the previous node to 
point to the left node of the node to delete (assuming that it exists). 


ee 
ie ee 


a aoe 


ed 
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Second, you must assign the right node of the node to delete to the 
first node in the new chain that points to NULL. 


+ 


Es 
NULL 


ane 
No 


a eee 


The following routine performs a binary tree deletion: 


/* 

* Gelete Cree (value; start) 

* 

* Remove a node containing the value specified from a binary tree. 
* 

* value (in): Value to delete. 

* start (in): Pointer to the first node in the list. 

* 

* status = delete (5, &root); 

* 

* If multiple nodes contain the value specified, only the first 

* node found is deleted. This routine uses the routine 

* delete tree entry if the the root does not point to the desired 
* value. 

* 

~ 


delete tree (int value, struct list_entry **start) 
{ 


struct list entry *current. node; 


if (value == (*start) ->value) 


if ((*start) ->left) 
current node = (*start)->left; 
else if ((*start) ->right) 
current node = (*start)->right; 
else 
return (1); 
while (current _node->right) 
current _node = 
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/* only one node in the tree */ 


current _node->right; 


if (current. node != (*start)=>right) 


current_node->right = 


current node = *start; 


1f ((*start) ->left) 
*start = (*start)->left; 
else if ((*start) ->right) 
*start = (*start)->right; 


free (current. node) ; 
return (0); 


} 


else if (value < (*start) ->value) 


(*start) ->right; 


return (delete tree entry (value, *start, (*start)->left)); 
else 
return (delete tree entry (value, *start, (*start)->right)); 
} 
/* 
* delete tree entry (value, previous, node) 
* 
* Remove a node containing the value specified from a binary tree. 
* 
* value (in): Value to delete. 
* previous (in): Pointer to the node preceeding the current node. 
* node (in): Current node in the binary tree. 
* 
x Status = delete: tree-entry (5). reoty .oot=>next)’; 
k 
* This routine is called by delete tree when the root does not 
* contain the value desired. 
* 
xf 


delete tree entry (int value, struct list_entry *previous, 


Struct: List entry 
{ 


struct list _entry *current_node; 


int result = -1; 
if (node == NULL) 
return (-1); 
if (node->value == value) 
ae (previous->left == node) 


previous->left = NULL; 


*node) 


O¢7 
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if (previous->value < value) 
{ | . . 
previous->right = node->left; 
current node = previous; 


while (current node->right) 3 
current node = current_node->right; 


current node->right = node->right; 


else 


{ 
previous->left = node->left; 


current _node = previous; 


if: (current. .node=> Ler) 


{ 
current node = current_node->left; 


while (current _node->right) 
current node = current _node->right; 


current _node->right = node->right; 


} 
else | 
current _node->left = node->right; 
} - 


free (node); 
result = 0; 
} 


else if (node->value > value) 


if (node->right) 
result =.delete tree entry (value, node; node->right); 


if ((node->left) && (result == -1)) 

result = delete tree entry (value; node, node=>left) ; 
else 

return (-1); 


} 


else 


{ 
if (node->left) 
result = delete tree entry (value, node; node->lerit) ; 


if ((node->right) && (result == -1)) 7 
result = delete tree entry (value, node, node->right); 


else 
return (=1)> 


} 


return (result); 


} 


The following program uses a binary tree to display the contents 
of a small file in sorted order: 
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#include <stdio.h> 


StCPUCE List enery. 4 

char value[132]; 

struct list entry *right; 
struct list entry *left; 
} 3 


main (int argc, char xargqvi[j) 


{ 


void *calloc (unsigned, unsigned), free tree (); 
struct list _entry *start, *node, *new_node; 
FILE *fopen (), *fp; 
char line[132]; 
ai Karas -< 2) 
{ 
printf ("SORT: Invalid usage: SORT FILENAME.EXT\n") ; 
exit (1); 
} 
else if (! (fp = fopen (argv[1], "“r"))) 
{ 
printf ("SORT: Unable to open the file %s\n", argv[1]); 
exit (1); 
} 
else if ((start = (struct list_entry *) 
calloe (1, Sizéof (struct 11st entry) )) “== NULL) 


{ é 
printf ("Unable to allocate memory for the list\n"); 
exit (1); 


else 
{ 
node = start; 
node->right = NULL; 
node->left = NULL; 
fgets (start->value, 


sizeof(line), fp); 


} 


while Sizeof(line), 
{ 
if (tree insert 


{ 
printf ("Unable to allocate memory for the list\n"); 


(fgets (line, fp) ) 


(line, start) == -1) 


exit (1); 
} 
} 
fclose (fp); 
show tree (start); 


free tree (start); 


} 
int Cree. insert (char *value, struct Jist sentry *node) 
| 


void calloc(); 


if (string comp (value, node->value, 0) == 2) 


379 


380 TURBO C PROGRAMMER'’S LIBRARY 


if (node->left != NULL) 
tree insert (value, node->left); 
else 


if ((node->left.= (struct list. entry *) 
calloc(1, sizeof(struct list_entry))) == NULL) 
return (-1); 


(node->left) ->right = NULL; 
(node->left) ->left = NULL; 
copy string (value, (node->left)->value, 132); 


else 
if (node->right != NULL) 
tree insert (value, node->right); 
else 


if ((node->right = (struct list _entry *) 
calloc(1, sizeof(struct list _entry))) == NULL) 
return (-1); 


(node->right) ->right = NULL; 
(node->right) ->left = NULL; 
copy string (value, (node->right)->value, 132); 


return (0); 


} 


show_tree (struct list_entry *node) 


{ 
if (node->left) 
show tree (node->left); 


printf ("%$s\n", node->value) ; 
if (node->right) 


show_tree (node->right) ; 
} 


The code fragments in this chapter are intended to provide foun- 
dations on which you can build your programs. 


Memory Mapping 


Chapter 3 examined the use of pointers in Turbo C string manipula- 
tion. That discussion showed that a pointer is a value that "points to” 
(or references) a specific location in memory and that most pointers 
reference memory locations contained within a 64K data segment. 


char *ptr; 


Although the following pointers could easily access all of the 
memory locations within the example region, the pointers cannot 
access memory locations beyond the region. 


381 
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| Code 
ae segment Pe 

(] Data ] 
64K | segment _ oho char =ptr, 
gan 

| segment 


SS 


Memory 


Pointers of this type are often called near pointers because the 
locations they reference must be within a 64K region. Memory loca- 
tions within the IBM PC and PC compatibles are addressed by way 
of a segment and offset combination. The segment address defines 
the location of a specific 64K region. The offset address is used to 
access Individual memory locations with the segment, as shown in 
Figure 14-1. | 

A program that performs memory mapping uses a segment and 
offset address to access specific memory locations. The most common 
use of memory mapping is for input and output. 

Chapters 6 and 7 examined several DOS and BIOS services that 
perform sophisticated I/O operations. However, in some cases these 
services are simply too slow. As a result, many programmers 
instead place output characters directly into the video display. 

~memory. | 

The IBM PC and PC compatibles set aside a region of memory 
called the video display memory. Before a letter can appear on your 
screen, it must reside in the video display memory. Depending on 
your monitor type, the following memory locations are used: 
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Segment Offset 


FFFE:FFF8 | FFF8 
FFFE:FFF9 


FFFE 


FFF9 
FFFA 
FFFB 


FFFE:FFFA | 


FFFE:FFFB 
FFFC 


FFFE:FFFC 
FFFE:FFFD 
FFFE:FFFE 


FFFD 
FFFE 
FFFF 


FFFF 0000 


0001 


0002 
0003 


FFFF:0009 
FFFF:000A 


Memory 


0004 
0005 
0006 
0007 
0008 
0009 
000A 


Figure 14-1. Adding offsets to access memory locations 


384 
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B000:0000 
oe B800:0000 


Color display 


Memory 


Picture the video display memory as a two-dimensional array 
with 25 rows and 160 columns (see Figure 14-2). The 25 rows corre- 
spond to the 25 rows on your screen. Remember, each character dis- 
played on the screen has an attribute byte with which it is asso- 
ciated. Thus, the value 160 is calculated by the following equation: 


80 screen columns * 2 bytes (character and attribute) 


To place a letter in the upper-left corner of the screen, you would 
reference the following memory locations: 


0x B0000000 (Monochrome display) 
0x B8000000 (Color display) 


The attribute for the letter must reside in the memory location 
immediately following the character, as shown here: 


0x B0000001 (Monochrome display) 
0xB8000001 (Color display) 


row 0 


row O, 
column 0 
character 


row 1, 
column 0 
character 


row 24, 
column 0 
character 


Figure 14-2. 


row 0, 
column 0 
attribute 


row 1, 
column 0 
attribute 


row 24, 
column 0 
attribute 


row O, 
column 1 
character 


row 1, 
column 1 
character 


row 24, 
column 1 
character 


row 0, 
column 1 
attribute 


row 1, 
column 1 
attribute 


row 24, 
column 1 
attribute 


row 0, 


column 79 


character 


row 1, 


column 79 


character 


row 24, 


column 79 


character 
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row O, 
column 79 
attribute 


row 1, 
column 79 
attribute 


row 24, 
column 79 
attribute 


Two-dimensional array of video display memory 


The following program displays the letter ”A” in the upper-left 
corner of a color screen display. Unlike previous programs that used 
a 16-bit (offset) pointer to a location in the data segment, this pro- 
gram uses a far pointer that allows you to define a segment and 
offset combination. 


main () 


{ 


char far *ptr 


*ptr 


a 


= ies 


0xB8000000; 


386 TURBO C PROGRAMMER’S LIBRARY 


With the previous addressing scheme in mind, you can determine 
the memory location at which to display a character, as shown here: 


char “far “ptr; 


ptr = (char far *) (0xB8000000 + (row * 160) + (column * 2)) 


The following program displays the letters "A-Z” in the middle 
of your screen and constantly changes their display attributes: 


ABCDEFGHIJKLMNOPORS TUVWXYZ 


main () 
{ 


char far *ptr, letter; 


int i, j, row = 10, column = 25, attr; 
ptr = (char far *) (0xB8000000 + (row * 160) + (column * 2)); 


EOr (i = 0, letter = ‘A’; letter <= 'Z'; i += 2, lettert+t) 
*(ptr + i) = letter; 


for (i = 1; i < 100; i++) 
for. (attr = ly attr <= 2557. atcrt+) 
for (j = 1, letter = ‘A’; letter <= 'Z’; j t= 2, lettertt) 
(pera = akury 


Depending on your type of monitor, you may begin to experience 
snow on your screen display as the program executes. This is 
because of the manner in which the IBM PC updates the display. 
Every one-eighteenth of a second, the PC performs a horizontal 
retrace of the contents of the screen to refresh the screen display. If 
you access the video display memory during this retrace cycle, snow 
is likely to occur. —_ 

To prevent snow from appearing, you must determine when the 
retrace is in effect and coordinate your video memory accesses with 
the retrace. The IBM PC and PC compatibles use the first bit in the 
value contained in port 0x3DA to specify when the retrace is active. 
Knowing this, you can obtain this value and determine when to per- 
form your I/O operations (see Figure 14-3). 
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Has — 
retrace 
begun? 


Update screen 
display 


Figure 14-3. Processing to determine when to perform I/O operations 


Turbo C provides a run-time library routine called inportb that 
returns the byte value from a port. As such, you would assume that 
you could use the following code fragment to control your output: 


while ((inportb(0x3DA) & 1) != 1) 


tf 


while ((inportb(0x3DA) & 1) == 1) 


° 
f 
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Unfortunately, the horizontal retrace occurs so fast that by the time 
this fragment completes, you do not have time to output the charac- 
ter. You can use the following assembly language routine instead: 


/ 


+ + + + FH HF HF HH HF HF HF OF 


void memory map put (segment, offset, value) 


Map the given value into a memory location within the video 
display memory. Insure that the memory reference is in 
syne with the horizontal retrace. 


segment (in): Segment address of the video display memory. 
offset (in): Offset address within the video display memory. 
value (in): Value to place into the memory. 


memory map _ put (0xB800, 0, 65); 


void memory map put (int segment, int offset, int value) 


#pragma inline 


} 


asm push DX 

asm push ES 

asm push DI 

asm push BX 

asm push AX 

asm MOV ES, segment 
asm MOV DI, offset 
asm MOV BX, value 
asm MOV DX, O3DAH 
asm IN Alig. Dx 
asm TEST AL, 1 

asm JNZ A 

asm CLI 

asm IN AL, DX 
asm TEST AL, 1 

asm JZ B. . 

asm MOV BYTE PTR ES:[DI], BL 
asm STI 

asm pop AX 

asm pop BX 

asm pop DI 

asm pop ES 

asm pop DX 


This routine receives a segment and offset address along with the 
value to be placed in the memory location. Since the routine does not 
have the same overhead as the previous Turbo C code fragment, you 
have time to output the desired value. 
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To use inline code within Turbo C programs, you must use the 
Microsoft macro assembler to assemble the code. Invoke the Turbo C 
compiler and linker from the command line, as shown here: 


C> TCC FILENAME.C 


Turbo C will take care of invoking the macro assembler for you. 


Turbo C Inline Code 
To use inline code from within a Turbo C program, you must have the 
Microsoft macro assembler. Next, invoke the Turbo C compiler from the 


command line, as shown here: 


C> TCC FILENAME.C 


You can now use this code fragment to place the letters ”"A-Z” on 
the screen and constantly update the attributes of the letters, as 
shown here: 


main () 
{ 


void memory map put (int, int, int); 
int letter, i, j, offset, row = 10, column = 25, attr; 
offset = (row * 160) + (column * 2); 


for (i = 0, letter = /A’; letter <= '2'; i += 2, letter++) 
memory map put (0xB800, offset + i, letter); 


for (i = 1; i < 100; i++) 
for (attr = 1; attr <= 255; attr+t+t) 
for (j = 1, letter = ‘A’; letter <= 'Z'; 3 += 2, letter+t+) 
memory map put (0xB800, offset + j, attr); 


No snow will appear this time. 
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Video Display Pages 


Depending on your type of monitor, you may save a considerable 
amount of memory set aside for video display output. Since a screen- 
ful of information requires only 4000 bytes (25 * 160) of storage, the 
additional memory can be divided up into additional video display 
buffers called pages. For example, in 80 mode the color graphics 
adapter (CGA) has space for four video display pages, as shown 
here: | 


Color graphics 


B800 
Video page 0-4K | 
Video page 1-4K 
Video page 2-4K 
Video page 3-4K 


Adapter 


16K 
Display 


Memory 


Memory 


Each video display page is capable of storing a screenful of 
information. Many of the routines in Chapter 7 allowed you to output 
to a specific display page. In most cases, you will use display page 0. 
However, by utilizing video display pages, you can often increase the 
flair of your applications by making output appear instantaneously. 
For example, the following program writes a screenful of letters to 
page 1 and then selects that page as the active display page: 
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#include <stdio.h> 


main () 
{ 
dn dey 
Void “set-Cursor positon: 4); 
void set_active display page (); 
for (i = 0; i < 25; i++) 
{ 
SeL cursor position (1, 2, 0)? 
write char and attr (1, ’A’, 7, 80); 
} 


set _active display page (1); 

getchar (); 

set active display page (0); 
} 


In so doing, the page of letters appears instantaneously. 

Note that the previous program resets the video display back to 0 
before terminating. Many applications that perform memory- 
mapped [I/O fail to check which display page is active. As such, 
these applications only display output to page 0. If you do not reset 
the active display page to 0 before terminating, other applications 
may not work. Also note that the application simply exits if the dis- 
play is monochrome. This is because the monochrome system does 
not support video display pages. 

Video display pages can be quite convenient. You can use 
memory-mapped I/O to increase the speed of applications that use 
video display pages. The PC sets aside 4096 bytes for each video 
display page. Knowing that the starting memory location is 
0xB8000000, you can compute the location of each video display 
page as shown here: 


page location = 0xB&8000000 + (page * 4096); 
With this in mind, the following routines implement several con- 


venient I/O routines. The first, clear—display—page, clears the con- 
tents of the specified video display page. 
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int page = 0; clear__display__page 


void clear display page (page) 


Clear the screen display by setting each character on the 
screen to an ASCII 32 (space character). 


page (in): Video display page to clear. 
clear display page (0); 
This routine only supports 80 column mode. 


/ 


+ + + HF F FF HF HF HF OF KF KE 


void clear display page (int page) 
{ 
int width, mode, current page, i, j, segment, offset; 


void get video mode (int *, int *, int *); 
void memory map put (int, int, int); 


get_video mode (&width, &mode, &current_ page); 


/* only support 80 column text mode */ 
if ((width != 80) || (page > 3)) 
return ; 


if (mode == 7) 
{ 
page = 0; 
segment = 0xBO000; 
{ 
else 
segment = 0xB800; 
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for (i = 0; i <= 25; itt) 
{ 
offset = (page * 4096) + (i * 160); 


for (j= 07.3. <= 79% 9+4) 
memory map put (segment, offset + (j * 2), 32); 


Next, clear—tline erases the contents of the specified line from 
the desired video page. 


int page = 0; 
int row = 10; 


clear__line 


/* 

* void clear line (page, row) 

* 

* Clear a line on the screen display by setting each character 
* on the line to an ASCII 32 (space character). 
* 

* page (in): Video display page desired. 

* row (in): Display row to clear. 

* : 

* clear line (0, 10); 

* 

* This routine only supports 80 column mode. 

* 

ag 


void clear line (int page, int line) 
{ 


int width, mode, current page, i, segment, offset; 
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void get_video mode Ont *) ant: *;° tae. +)¢ 
void memory map put (int, int, int); 


get_video mode (&width, &mode, &current page); 


if ((width != 80) || (page > 3)) 
return ; 


if (mode == 7) 
{ 
page = 0; 
segment = 0xB000; 
} 
else 
segment = 0xB800; 


offset = (page * 4096) + (line * 160); 
for (i = 0; i <= 79; i++) 


memory-Map put (segment, offset + (i * 2); 32); 
} 


The routine set—display__page—attribute sets the attribute byte 
for all of the characters on a specific video display page. 


int page = 0; 
int attribute = 7; 


set_display__page—attribute 


void set_display page attribute (page, attribute) 


Set the character display attribute for the video display 
page specified. 


page (in): Video display page desired. 
attribute (in): Desired video attribute. 


tee ** * * * 
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* set_display page attribute (0, 7); 

* 

* This routine only supports 80 column mode. 

* 

my 

void set_display page attribute (int page, int attribute) 
{ 


int width, mode, current page, i,j, segment, offset; 


Void -get video mode: “int yt. Ay ant “*)y 
void memory map put (int, int, int); 


get _video mode (&width, &mode, &current page); 


if ((width != 80) I| (page > 3)) 
return ; 
if (mode == 7) 
{ 
segment = 0xB000; 
page = 80; 
} 
else 


segment = 0xB800; 
for (1. = 07 4..<= 257 144) 
{ 
offset = (page * 4096) + (i * 160); 


for (j= Of 9 <= 795 344) 
memory map put (segment, offset + (j * 2) + 1, attribute); 


In a similar manner, the routine set—line—attribute sets the 
video display attribute for a specific row on the screen display. 


int page = OQ; 
int line = 10; set__line__attribute 
int attribute = 7; 
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void set_line attribute (page, line, attribute) 


Set the character display attribute for a line on the video 
display page specified. 


page (in): Video display page desired. 

line (in): Row to set the display attribute for. 
attribute (in): Desired video attribute. 
set_line attribute (0, 10, 7); 


This routine only supports 80 column mode. 


/ 
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void set line attribute (int page, int line, int attribute) 
{ 


int width, mode, current page, i, segment, offset; 


void get_video mode (int *, int *, int *); 
void memory map put (int, int, int); 


get_video mode (&width, &mode, &current_page); 


if ((width != 80) || (page > 3)) 
return ; 


if (mode == 7) 
{ 
segment = 0xB000; 
page = 0; 
} 


else 
segment = 0xB800; 


offset = (page * 4096) + (line * 160); 
for (i = 0; i <= 79; i++) 


memory map put (segment, offset + (i * 2) + 1, attribute); 
} 


Next, buffer__screen—region saves the contents of a video dis- 
play page (or region) on the display page. 


+ + + + + F KF FF OF OF 
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int page = 0; 

int top = 10; 

int bottom = 20; 
int left = 10; 

int right = 70; 
char buffer[size]; 


buffer__screen__region 


Screen characters 
and attributes 


void buffer screen region (page, top, bottom, left, 
right, buffer) 


Store a region of the screen display into the buffer provided. 


page (in): Video display page desired. 


‘top (in): Top row of the region to save. 


bottom (in): Bottom row of the region to save. 

left (in): Leftmost column of the region to save. 
right (in): Rightmost column of the region to save. 
buffer (out): Buffer containing the region to store. 
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buffer _screen_region (0, 10, 20, 0, 79, buffer); 


Remember that you are buffering not only the characters, but 
also the attributes. As such, your buffer size needs to be: 


/ 


2 * ABottom = top). -* (right: —. Lefer) 


void buffer screen region (int page, int top, int bottom, 


} 


{ 


int i, j, k = 0; 


int offset, 


int left, 


segment, mode, width, 


int riot; 


current page; 


void get video mode (int *, int *, int *); 


get_video mode (&width, &mode, &current page); 


if ((width != 80) 


|! (page > 3)) 


return ; 
if (mode == 7) 
{ 
page = 0; 
segment = 0xB000; 
} 
else 
segment = 0xB800; 


for (i = top; i <= 


} 


offset = (page 


for (j = left; 
{ 


} 


buffer [k++] 
buffer [k++] 


* 
3 


bottom; i++) 


4096) + (i * 160); 


<= right; jt+t) 


memory map get 
memory map _ get 


(segment, 
(segment, 


offset + 
offset + 


¥ 


char *buffer) 


(J * 2)) 
C2) 


e 
, 


+ 1) 
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Just as an assembly language routine was required to place 
values into the video display memory, the following routine reads a 
byte from the specified segment and offset location. 


int segment = 0xB800; 
int offset = 0; 


memory__map__get 


Character or attribute 
at the specified location 


memory map_get (segment, offset) 


Return the value contained ina memory location within the video 
display memory. Insure that the memory reference is in sync with 
the horizontal retrace. 


segment (in): Segment address of the video display memory. 
offset (in): Offset address within the video display memory. 


+ + + + FF HF 
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* 


* value = memory map get (0xB800, 0); 
* 


ad 4 
memory map get (int segment, int offset) 
{ 


char value; 


#pragma inline 


asm push DX 
-asm push ES 
asm push DI 
asm push AX 
asm MOV ES, segment 
asm MOV DI, offset 
asm MOV DX, OSDAH 
A: 
asm IN AL, DX 
asm TBoOr AL, 1 
asm JNZ A 
asm CLI 
B: . 
asm IN AL, DX 
asm TEST . AL, 1 
asm JZ B 
asm MOV al, BYTE PTR. ES: {DL} 
asm MOV value, al 
asm STI 
asm pop AX 
asm pop DI 
asm pop Eis 
asm pop DX 


return (value); 


In a similar manner, the routine restore—_screen—region restores 
a previously buffered region of the video display. 
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int page = 0; 
ET aa 
int top = 10; 
int bottom = 20; 
restore__screen_region. 
int left = 10; 
: . Ae. 
int right = 70; 


char buffer[size]; 


void restore screen region (page, top, bottom, left, 
right, buffer) 


Restore a previously stored region of the screen display 
from the buffer provided. 


page (in): Video display page desired. 

top (in): Top row of the region to restore. 

bottom (in): Bottom row of the region to restore. 

left (in): Leftmost column of the region to restore. 
right (in): Rightmost column of the region to restore. 
buffer (out): Buffer containing the region to restore. 


restore screen region (0, 10;. 20; 0, 79, buffer); 


j 
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void restore screen region (int page, int top, int bottom, 
int left, int right, char *buffer) 
{ 
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Int ay, K-=— "Os 
int offset, segment, mode, width, current page; 


Vold get video-mode (int *%," ant: *)inkt. *);7 
void memory map put (int, int, int); 


get_video mode (&width, &mode, &current page) ; 


if ((width != 80) || (page > 3)) 
return ; 


if (mode == 7) 


page = 0; 
segment = 0xB000; 


} 
else 
segment = 0xB800; 


for (i = top; i <= bottom; itt) 
SSheSee = (page * 4096) + (i * 160); 
for (j = left; j°<= right; jtt+) 
enbey Atosat (segment, offset + (j * 2), buffer[k++]); 
memory:map put (segment, offset +-(j * 2) + 1, buffer[k++]); 


} 
} 


The routine put—line writes a character string to the video 
memory by using the specified attribute. 


int page = 0; 

int row = 10; 

int attribute = 7; 
Char «str = "TEST"; 


put__line 


MEMORY MAPPING 403 


rs * 
* void put _line (page, row, attribute, line) 
* 
* Place a character string at the row specified using the 
* display attribute given. 
* i « 
* page (in): Video display page desired. 
* row (in): Display row to place the string at. 
* attribute (in): Desired video display attribute. 
* line (in): Character string to display. 
* 
* put. line 40; 10, 7 “This: is a test"); 
* 
* This routine only supports 80 column mode. 
* 
a | 


void put _line (int page, int line, int attribute, char *str) 
{ 


int width, mode, current page, i, segment, offset; 


void get video mode (int *, int *, int *); 
void memory map put (int, int, int); 


get_video mode (&width, &mode, &current_page); 


if ((width != 80) || (page > 3)) 
return ; 
if (mode == 7) 


{ 
segment = 0xBO000; 
page = 0; 
} 
else 
segment = 0xB800; 


offset = (page * 4096) + (line * 160); 
for (1 = 0; i <= 795 i++) 
ie (7 Str) 
moni (segment, offset + (i * 2), *strt+t); 


memory map put (segment, offset + (i * 2) + 1, attribute); 
} 

else 
break ; 


Experiment with the routines presented in this chapter and you 
should find them to be quite fast. In fact, many of the I/O manipula- 
tion routines in this book can be converted to memory-mapped out- 
put if your needs require. Many of the routines in Chapter 15 are 
based on memory-mapped output. 


Menus and 
Special I/O 


Chapter 12 examined a series of I/O routines that greatly simplify 
your programming of the user interface. Those routines allow your 
programs to prompt for and obtain data from the user in a consis- 
tent manner, so users can feel more at ease with the programs they 
are running. However, anytime a user must interact with a pro- 
gram, the chance of human error increases. Many program develop- 
ers (and end users) prefer to develop menu-driven systems. 
Traditionally, menus have taken the following form: 


405 
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General Ledger 


Perform Payroll 
Accounts Receivable 


Print Checks 
Accounts Payable 
Past Due Accounts 


Here the user must enter the number that corresponds with a 
desired choice. 

As more people are exposed to computers on a regular basis, they 
begin to expect more from the user interface. The routines in this 
chapter address several expectations of users concerning menu- 
driven applications. They display the menu in a manner that is tra- 
ditional in appearance, but more flexible in functional capabilities, 
as shown here: 


General Ledger Accounting Package 


P Perform Payroll Operations 
R Update Accounts Receivable 
C Print Checks 

A Update Accounts Payable 

L Process Past Due Accounts 


Q Quit General Ledger Returning to DOS 


Press desired key or use arrow keys and press Enter 


The routines in this chapter support two extremes of user prefer- 
ences with regard to menus. The traditional "enter the correspond- 
ing letter or number” response is fully supported. In front of each 
menu option is a single character. If the user presses the the key that 
corresponds to that character, the option is selected. 

The second option involves the keyboard arrow keys. The current 
option is always highlighted. To select a different option, the user 
simply presses the UP ARROW or DOWN ARROW key to highlight a 
different option. Once the desired option is ee the user 
presses the ENTER key to select it. 


MENUS AND SPECIAL I/O 407 


A significant amount of code can be duplicated in menu-driven 
programs. In many cases, if you have several menus, you may have 
simply cut and pasted the required code. However, this chapter 
develops three standard menu-manipulation routines. Rather than 
duplicating code, you simply pass a structure containing the 
required menu information to the routine. The routine, in turn, dis- 
plays the appropriate menu and entry selections. 

The final topic examined in this chapter is pop-up menus. By 
building on routines presented in Chapter 14, pop-up menu process- 
ing becomes relatively simple. 


Menu Structure 


Each menu routine in this section is based on a menu structure that 
contains the following: 


struct menus { 
int num entries; 
char choices [15]; 
char *entries[15]; 
char *title; 
char *prompt; 


. 
a 


Each menu is restricted to a maximum of 14 entries. This restric- 
tion is not because of processing, but rather because of ease of use. If 
your menu contains too many entries, your screen becomes cluttered. 
Likewise, too many menu entries also become cumbersome to the 
end user. Given the following structure, 


struct menus { 
int num_entries; 
char choices [15]; 
char *entries[15]; 
char *title; 
char *prompt; 
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} payroll menu = 
{ 6, “PRCALQ", . 
{"Perform Payroll Operations", 
"Update Accounts Receivable", 
"Print Checks", 
"Update Accounts Payable", 
"Process Past Due Accounts", 
"Quit General Ledger Returning to DOS"}, 
“General Ledger Accounting Package", 
"Press desired key or use arrow keys and press Enter" 


the routine display—menu (which appears later in this chapter) dis- 
plays the following: | 


General Ledger Accounting Package 


P Perform Payroll Operations 
|| R Update Accounts Receivable 

C Print Checks 

A Update Accounts Payable 

L Process Past Due Accounts 


Q Quit General Ledger Returning to DOS 


Press desired key or use arrow keys and press Enter ~ 


Note the use of the choices field within the menu structure. Each 
menu option has a character that corresponds to it. The choices field 
defines those characters. 


Framing a Menu 


Each of the routines in this chapter provides a frame around the 
menus it displays. This tends to draw the attention of the user to the 
menu options. Depending on the number of entries in the menu, the 
size of the frame will differ from menu to menu. The routines use 
the extended ASCII character set illustrated here to box the menu: 
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The following code implements display—frame: 


int page = 0; 


int upper__row = 5; —_ 


int leftmost__column = 10; -> 


display__frame 
int lower__row = 20; —_ 


int rightmost_column = 70;—> 


int attribute = 64; — 
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void display frame (page, upper_row, leftmost_column, . 
lower row, rightmost_column, attribute) 


Using extended ASCII characters, display a box on the screen 
that can be used as a frame for messages or menus. 


page (in): Desired video display page. 

upper row (in): Top row of the display frame. 

leftmost column (in): Leftmost column of the display frame. 
lower_row (in): Lower row of the display frame. 

attribute (in): Video attribute desired. 


display frame (0, 10, 5, 20, 65, 64); 
/ 


+ + + FF F FF HF FHF HF HF HH HK - 


void display frame (int page, int upper row, 
int leftmost ,column, int lower row, 
int rightmost column, int attribute) 
{ 


int width, mode, current _page, i, segment, offset; 


void get_video mode (int *, int *, int *); 
void memory map put (int, int, int); 


get_video mode (&width, &mode, &current_page) ; 


if ((width != 80) || (page > 3)) /* only support 80 columns */ 
return ; 
if (mode == 7) 
{ 
segment = 0xB000; /* monochrome */ 
page = 0; 
} 
else 


segment = 0xB800; 
/* put in upper corners */ 


offset = (page * 4096) + (upper row * 160); 
memory map put (segment, offset + (leftmost column * 2), 201); 
memory map put (segment, offset + (leftmost column * 2) + 1, 
. attribute); 
memory map put (segment, offset + (rightmost_column * 2), 187); 
memory map put (segment, offset + (rightmost_column * 2) + 1, 
attribute); 


/* top row of frame */ 
for (i = leftmost_columnt+1l; i <= rightmost_column-1; i++) 
memory map put (segment, offset + (i * 2), 205); 
memory map put (segment, offset + (i * 2) + 1, attribute); 
} 
/* put in bottom corners */ 
offset = (page * 4096) + (lower row * 160); 
memory map put (segment, offset + (leftmost column * 2), 200); 


memory map put (segment, offset + (leftmost column eZ Ye a 
attribute); 
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memory map put (segment, offset + (rightmost column * 2), 188); 
memory map put (segment, offset + (rightmost column * 2) + 1, 
attribute) ; 


/* bottom row of frame */ 


for (i = leftmost _columntl; i <= rightmost _column-1; i++) 
{ 
memory map put (segment, offset + (i * 2), 205); 
memory map put (segment, offset + (i * 2) + 1, attribute); 


} 
/* put in the sides */ 


for (i = upper row + 1; i <= lower row -1; i++) 

{ 

offset = (page * 4096) + (i * 160); 

memory map put (segment, offset + (leftmost column * 2), 186); 

memory map put (segment, offset + (leftmost column * 2) + 1, 
attribute) ; 

memory map put (segment, offset + (rightmost _column * 2), 186); 

memory map put (segment, offset + (rightmost column * 2) + 1, 
attribute) ; 


Displaying and Using a Menu 


The following routine displays a menu on the screen. As previously 
stated, the menu is surrounded by a frame, and provides a user 
prompt at the bottom of the screen, as shown here: 


Printer Selection 


H Select HP Laser Printer 

P Select PostScript Laser Printer 
L Select Letter Quality Printer 

D Select Dot Matrix Printer 


Press desired key or use arrow keys and press Enter 


The following routine, display__memo, displays a menu: 
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vo 


{ 


int page = 0; 
struct menus menu; display__menu 
int attribute = 64; | 


void display menu (page, menu, attribute) 
Display a menu on the video display page specified. 
page (in): Video display page desired. . 
menu (in): Structure containing desired menu. 
attribute (in): Video display attribute for the menu. 
display menu (0, main_menu, 7); 
/ 
id display menu (int page, struct menus menu, int attribute) 
int upper _row, lower row, leftmost_column, rightmost column; 
int title row, prompt_row, title column, prompt column, max_size; 
int width, mode, current page, i, j, segment, offset; 
void get_video mode (int *, int *, int *); 
void memory map put (int, int, int); 


void display frame (int, int, int, int, int, int); 


get_video_mode (&width, &mode, &current_page); 


if ((width != 80) || (page > 3)) 
return ; /* only support 80 column */ 
if (mode == 7) /* monochrome system */ 


{ 
segment = 0xB000; 
page = 0; 
} 
else 
segment = 0xB800; 


/* determine upper and lower frame row */ 
upper row = 13 - 4 - (menu.num_entries / 2); 


lower row = 13 + 1 + ((menu.num entries % 2) ? 
((menu.num_ entries + 1) / 2): (menu.num_entries / 2)); 
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/* determine title location and display title */ 


title row = upper row + 2; 


for (1 = 0; menu.title[i]; i++) ; 
title column: = 39 = (i. /-2)y 
offset = (page * 4096) + (title row * 160) + (title column * 2); 


for (i = 0; menu.title[i]; i++) 
{ 
memory map put (segment, offset + (i * 2), menu.title[i]); 
memory map put (segment, offset + (i * 2) + 1, attribute); 


} 


max Size = i; /* largest string display thus far */ 
/* frame size is relative */ 


/* determine largest string for frame size */ 


for (i = 0; i < menu.num entries; i++) 
{ 
for (j = 0; menu.entries[i] [j]; j++) 


’ 
if (j > max_size) 
max size = j; 


} 
/* center menu on column 39 */ 


leftmost_column = 39 - ((max_size + 8) /2); 
rightmost_column = 39 + ((max_size + 8) /2); 


display frame (page, upper row, leftmost’ column, 
lower row, rightmost column, 7); 


/* display the menu choices */ 


for (i = 0; i < menu.num entries; i++) 
{ 
offset = (page * 4096) + ((title row + 2 + i) * 160); 
memory map put (segment, offset + (leftmost_column + 2) * 2, 
menu.choices[i]); 
memory map put (segment, offset + (leftmost _column + 2) * 2 +1, 


attribute); 


offset = (page * 4096) + ((title row + 2 + i) * 160) + 
(leftmost column + 4) * 2; 


for (j = 0; menu.entries[i] [4]; j++) 
{ 
memory map put (segment, offset + (j * 2), menu.entries[i][j]); 
memory map put (segment, offset + (j * 2) + 1, attribute); 
} 
} 


/* determine the location for the menu prompt and display it */ 


prompt row = 23; 

for (i = 0; menu.prompt[i]; i++) ; 

prompt column = 39 - (i / 2); 

offset = (page * 4096) + (prompt _row * 160) + (prompt _column * 2); 
for (1 = 0; menu.prompt[i]; i++) 
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{ 
memory map put (segment, offset + (i * 2), menu.prompt{[i]); 
memory map put (segment, offset + (i * 2) + 1, attribute); 
} 
} 


Once the menu is displayed, the following routine obtains the user 
selection: 


int page = 0; 

struct menus menu; 

int default_choice = 0; 
int attribute = 64; 


get_menu__response 


Index of the desired 
menu option 


re 

* get_menu_response (page, menu, default _choice, attribute) 
* 

* Get the user’s response to the menu specified. 

* 

* page (in): Video display page desired. 

* menu (in): Structure containing the desired menu. 

* default_choice (in): Default menu option. 

* attribute (in): Desired video attribute. 

* 

* selection = get_menu_response (0, main_menu, 0, 64); 
* 

* 


; 


get_menu_response (int page, struct menus menu, 
| int default_choice, int attribute) 
{ 
int upper row, leftmost column; 
int width, mode, current page, i, j, segment, offset; 
int done = 0, row, old _ row, max size, choice, valid key; 


void get_video_ mode (int *, int *, int *); 
void memory map put (int, int, int); 
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get_video mode (&width, &mode, &current_page) ; 


if ((width != 80) |{ (page > 3)) 
return ; /* only support 80 column */ 
if (mode == 7) /* monochrome system */ 


{ 
segment = 0xB000; 


page = 0; 
aed 
segment = 0xB800; 
upper row = 13 - 4 - (menu.num_entries / 2); 
for (i = 0; menu.title[iJ; i++) ; 
max size = i; /* largest string display thus far */ 


/* frame size is relative */ 
/* determine the largest string in the menu */ 


for (i = 0; i < menu.num_entries; i++) 
{ 
for (j} = 0; menu.entries[i][j]; j++) 


s 
if (j > max_size) 
max size = j; 


} 
/* determine the leftmost column based on centering */ 


leftmost_column = 39 - ((max_size + 8) /2); 
row = default choice; 


/* get the user response */ 
while (! done) 
/* determine and highlight the current row */ 


offset = (page * 4096) + ((upper row + 4 + row) * 160); 

memory map put (segment, offset + (leftmost column + 2) * 2 + 1, 

offset = (page * 4096) + ((upper row + 4 + row) * 160) + 
(leftmost column + 4) * 2; 


for (j = 0; menu.entries[row] [j]; j++) 
memory map put (segment, offset + (j * 2) + 1, 7); 


choice = no echo read(); 
valid _key = 0; 
old row = row; 


/* see if the user pressed a function or arrow key */ 


if (choice == 0) 
{ 
choice = no_echo_read(); 
Switch (choice) { 
case: 722-15 (row =. 0) 2/* “up arrow */ 


Ald 
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row = menu.num_entries - 1; 
else 

row--; 
valid key = 1; 
break; 


case 80: if (row == menu.num entries - 1) 
row = 0; /* down arrow */ 
else 
rowt++; 
valid key = 1; 
break ; 
} 
if (valid key) 
{ 


/* dehighlight previous row, highlight new row */ 


offset = (page * 4096) + ((upper row + 4 + old _ row) * 160); 
memory map put (segment, offset + (leftmost_column + 2) * 2 +1 
attribute); 
offset = (page * 4096) + ((upper_row + 4 + old _ row) * 160) + 
(leftmost. column, ‘+, 4). *.2; 


for (j = 0; menu.entries[old row][j]; j++) 
memory map put (segment, offset + (j * 2) + 1, attribute); 


offset = (page * 4096) + ((upper_ row + 4 + row) * 160); 
memory map put (segment, offset + (leftmost column + 2) * 2+ 1 


v 
offset = (page * 4096) + ((upper row + 4 + row) * 160) + 
(leftmost column + 4) * 2; : 

for (j = 0; menu.entries[row] [j]; j++) 
memory map put (segment, offset + (j * 2) + 1, 7); 


else 

{ : 

if (choice == 13) /* carriage return */ 
return (row); 

else /* test letter pressed */ 
for (i = 0; i < menu.num_entries; i++) 

if ((choice == menu.choices[{i]) || 
((choice & ~32) == menu.choices[i])) 


return (i); 


The routines are implemented separately simply to reduce the 
amount of code in each function. 
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Pop-Up Menus 


Most applications that use menus to prompt the user for information 
normally clear the screen display and then place the menu on a 
blank screen. However, in some eases, it is more convenient for the 
end user to leave the current display active and to place the menu in 
a corner of the screen display, as shown here: 


Source Code Display tate: California Zip: 81203 


A Display Ada Programs bats right, 415 lifetime average. 


B Display BASIC Programs 
C Display C Programs with the Giants. 
D Display DBASE Programs 


Press desired key or use arrow keys and press Enter 


Once the user makes a selection, the menu disappears, as shown 
here: 


Enter Name: Kevin Shafer 
Address: 1234 - First Ave 
City: San Francisco State: California Zip: 81203 


Description: Short stop, bats right, 415 lifetime average. 


Brief stint with the Giants. 


Such a menu is called a pop-up menu, since it apparently appears 
from nowhere and overlays the current contents of the screen. Pop- 
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up menu processing is quite straightforward. First, you simply save 
to a buffer (containing characters and their attributes) the contents 
of the section of the display that you will overwrite. Next, you dis- 
play and process the menu that obtains the user selection. Lastly, 
you must restore the screen contents that were previously buffered 
(see Figure 15-1). 3 

Using the routines buffer_video_region and restore—video 
region presented in Chapter 14, the processing becomes quite sim- 
ple. The routines are based on the menu type previously discussed. 
The only difference is that the routines now allow you to pass the 
coordinates of the upper-left corner of the menu. 

The following routine displays a video pop-up menu to the screen. 
Assuming that the menu structure is as follows, | 


struct menus { 
int num_entries; 
char choices [15]; 
char *entries[15]; 
char *title; 
char “prompr; 
} prt_menu = { 4, “HPLD", 
{"Select HP Laser Printer", 
"Select PostScript Laser Printer", 
"Select Letter Quality Printer", 
"Select Dot Matrix Printer"}, 
"Printer Selection", 
"Press desired key or use arrow keys and press Enter" 


the invocation 


~ 


display popup _ menu (0, 1, 2, prt_menu, 7); 
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Buffer screen 
region 


Display pop-up 
menu 


Get user selection 


Restore screen 
region 


Figure 15-1. Processing involved in pop-up menu display 
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displays the following: 


+ + & & He HH HH HK Ke 


Printer Selection 


H Select HP Laser Printer 
P Select PostScript Laser Printer 


L Select Letter Quality Printer 
D Select Dot Matrix Printer 


Press desired key or use arrow keys and press Enter 


The following routine implements display—popup—menu. 


int page = O; 
int row = 10; | 
int column = 25; display__popup__menu 


struct menus menu; 
int attribute = 7; 


void display popup menu (page, row, column, menu, attribute) 


Display the video popup menu specified. Save the previous 
screen contents restoring them once the popup is complete. 


page (in): Video display page desired. 

row (in): Desired upper row for the popup menu. 

column (in): Desired leftmost column for the popup menu. 
menu (in): Structure containing the popup menu. 
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attribute: Video display attribute desired. 
display popup menu (0, 0, 0, printer menu, 64); 


display popup menu relies on a global variable called buffer 
that it can store the current screen contents into. By making 
this variable global, it is easily accessed by the routine 
get_popup menu _ response which later restores the screen. 


+ * ££ + * + HF 


/ 


void display popup menu (int page, int row, int column, 
struct menus menu, int attribute) 
{ 
int upper _row, lower row, leftmost column, rightmost column; 
int title row, prompt row, title column, prompt column, max_size; 
int title size, width, mode, current page, i, j, segment, offset; 


void get video mode (int *, int *, int *); 

void memory map put (int, int, int); 

void buffer video region (int, int, int, int, int, char *); 
void display frame (int, int, int, int, int, int); 


get_video mode (&width, &mode, &current_ page); 


if ((width != 80) || (page > 3)) 
return ; /* only support 80 column */ 
if (mode == 7) /* monochrome system */ 


{ 
segment = 0xB000; 
page = 0; 

} 


else 
segment 


OxB800; 
/* save the previous screen contents */ 


buffer screen region (page, 0, 24, 0, 79, buffer); 


upper row row; 


lower row 


‘> row + 5 + menu.num entries; 
title row 


upper row + 2; 


for (i = O; menu.title[i]; i++) ; 


max size = i; /* largest string display thus far */ 
/* frame size is relative */ 


title size = i; 
/* determine the largest string in the menu */ 


for (i = 0; i < menu.num entries; i++) 
{ 
for (j = 0; menu.entries[i])[j]; j++) 
if (j > max_size) 
max Size = J; 


} 


leftmost _column = column; 
rightmost_column = max size + column + 8; 
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/* clear the screen region which will contain the menu */ 
for (i = row; i < row + 6 + menu.num_entries; i++) 
offset (page * 4096) + (i * 160); 


for (j = leftmost column; j <= rightmost_column; j++) 
memory map put (segment, offset +.(j * 2) + 1, 0); 


} 


/* determine the location of the title and display it */ 


Elie ‘column. = (column +8 + maxSize): / 2) = (Tit le<size: (..2):3 
offset = (page * 4096) + (title row * 160) + (title column * 2); 
for: 43 /= 07: Menu citlelas; ar) 


{ 
memory map put (segment, offset + (i * 2), menu.title[i]); 
memory map put (segment, offset + (1 * 2) + 1, attribute); 


} 


display frame (page, upper row, leftmost column, 
lower row, rightmost column, 7); 


/* display the menu choices */ 


for (1 = 07 4.<menu.num: entries; i++) 

{ : 

offset = (page * 4096): to (Little row + 2 oF 1) 8 460) ¢ 

memory map put (segment, offset + (leftmost column + 2) * 2, 
menu.choices[i]); 

memory map put (segment, offset + (leftmost column + 2) * 2 + 1, 
attribute); 

offset = (page * 4096) + ((title row + 2 + i) * 160) + 

(leftmost column + 4) * 2; 


for (j = O; menu.entries[i][j];  3++) 
{ 
memory map put (segment, offset + (j * 2), menu.entries[i][j]); 
memory map put (segment, offset + (j * 2) + 1, attribute); 
; | 
} 


/* determine the location of the prompt and display it */ 


prompt row = row + 7 + menu.num entries; 

for (i = 0; menu.prompt[{i]; itt) ; 

prompt column = column; . 

offset = (page * 4096) + (prompt_row * 160) + (prompt_column * 2); 


for (i = 0; menu.prompt[i]; i++) 
{ 
memory map put (segment, offset + (i * 2), menu.prompt[i]); 
memory map put (segment, offset + (i * 2) + 1, attribute); 
} 

} 


The following routine obtains a user response to the menu and 
then restores the previous screen contents: 
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int page = 0; 
int row = 10; 
int column = 10; 


struct menus menu; get_popup__menu__response 


int default__choice = 0; 
int attribute = 64; 


Index of the selected 
menu option 


/* 
* get_popup_menu_response (page, row, column, menu, 
* default choice, attribute) 
* 
* Get the user’s response to a video popup menu. Once the 
* response is known, restore the previous screen contents. 
* 
* page (in): Video display page desired. 
* row (in): Upper row of the display frame. 
* column (in): Leftmost column of the display frame. 
* menu (in): Structure containing the popup menu. 
* default choice (in): Default menu option. 
* attribute (in): Video display attribute desired. . 
* 
* get_popup_menu_response (0, 0, 0, printer menu, 0, 64); 
* 
. get_popup menu_response uses a global variable called buffer 
* which contains the screen contents to restore. 
* 
*/ 


get_ popup menu_response (int page, int row, int column, 
struct menus menu, int default choice, int attribute) 
{ 
int upper row, leftmost column; 
int width, mode, current _page, i, j, segment, offset; 
int done = 0, old_row, max_size, choice, valid key; 


void get_video_ mode (int *, int *, int *); 
void memory map put (int, int, int); 
void display frame (int;- int, int, int; ont) nt); 


get_video mode (&width, &mode, &current_page) ; 


if ((width != 80) || (page > 3)) 
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return ; /* only support 80 column */ 


if (mode == 7) /* monochrome system */ 
{ 
segment = 0xB000; 
page = 0; 


else 
segment = 0xB800; 


upper row = row; 
row: = default_choice; 
leftmost_column = column; 


while (! done) 
{ 


/* highlight the current option */ 


offset = (page * 4096) + ((upper_row + 4 + row) * 160); 
memory map put (segment, offset + (leftmost column + 2) * 2 + 1, 


Ud 


offset = (page * 4096) + ((upper_row + 4 + row) * 160) + 
(leftmost column + 4) * 2; 


for (j = 0; menu.entries[row] [j]; jtt) 
memory map put (segment, offset + (j * 2) + 1, 7); 


choice = no echo read(); 
valid_key = 0; 
Old_row = row; 


/* test if user pressed function or arrow key */ 


1f (choice == 0) 
{ , 
choice = no echo read(); 
Switch (choice) { 


case 72: if (row == 0) /* up arrow */ 
row = menu.num_ entries - 1; 
else 
row-—} 
valid key = 1; 
break; 


case 80: if (row == menu.num_entries - 1) 
| | row = 0; /* down arrow */ 


rowtt; 
valid_ key = 1; 
break ; 
} 
if (valid key) 
{ 


/* dehighlight previous option, hightlight new row */ 


offset = (page * 4096) + ((upper_row + 4 + old row) * 160); 
memory map put (segment, offset + (leftmost_column + 2) * 2 + 
attribute) ; . 
offset = (page * 4096) + ((upper_row + 4 + old _ row) * 160) + 
_(leftmost_column + 4) * 2; 
for (j = 0; menu.entries[old row] [Jj]; j++) 
memory map put (segment, offset + (j * 2) + 1, attribute); 
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offset = (page * 4096) + ((upper row + 4 + row) * 160); 

memory map put (segment,, offset + (leftmost column + 2) * 2 + 

offset = (page * 4096) + ((upper_row + 4 + row) * 160) + 
(leftmost column + 4) * 2; 

for (j} = 0; menu.entries[row] [j]; j++) 


memory map put (segment, offset + (j * 2) + 1, 7); 


if (choice == 13) /* carriage return */ 
{ 
restore screen region (page, 0, 24, 0, 79, buffer); 
return (row); 


} 


else /* test the letter entered */ 
for (i = 0; i < menu.num_entries; i++) 
if ((choice == menu.choices[i]) || 
((choice & ~32) == menu.choices[i]})) 


{ 
restore screen region (page, 0, 24, 0, 79, buffer); 
return (i); 


} 


Advanced Video Pop-Up Menus 


Video pop-up menus can be easily implemented. With them, your 
screen processing capabilities are virtually unlimited. Consider the 
following pop-up, which allows the user to add, subtract, multiply, 
or divide two numbers. 


| enemas || 
Value: 0.00000000 
Value: 
Result: 


F7 Addition F8 Subtraction 
F9 Multiplication F10 Division 


Enter first value. 
a renner} 


The routine can be very useful in cases where the user must 
enter a numeric response. If your program allows the user to press 
the F9 key, for example, to activate the pop-up, the user can first 
perform calculations and then respond to the numeric prompt. Once 
the user selects the Quit option, the original screen contents are re- 
stored. For example, if the user needs to know the result of 625 
divided by 17, the first entry would be 


| a nas | 
Value: 625.000000 


Value: 


| Result: 
F7 Addition F8 Subtraction 
F9 Multiplication F10 Division 


Enter first value. 
(oe | 


followed by 


a ee ee ee ee ee 
Value: 625.000000 
Value: 17.0000000 
Result: 
F7 Addition F8 Subtraction 
F9 Multiplication F10 Division 
Enter second value. 


eee | 


Once the user presses the F10 key for division, the result is displayed 
and the user is asked to press any key to continue. 


oe Sa 
Value: 625.000000 
Value: 17.0000000 
Result: 36.64705 


F7 Addition F8 Subtraction 
F9 Multiplication F10 Division 


Press any key to continue 


a 


+ + € & + F + £ F F HF F HK OK OF 


pope 
{ 
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The following routine implements the pop-up math processor: 


int page = 0; 


Result of 
math operation 


float calc (page) 
Display a video popup calculator on the display page specified. 
page (in): Desired video display page. 
result = calc (0); 
calc saves the current screen contents and then displays a 
Simple calculator. Once the operation is complete, calc 
restores the previous screen contents and returns the result 
of the operation. 
/ 
oat calc (int page) 
int upper _row, lower row, leftmost column, rightmost column; 
int attribute, width, mode, current page, i, j, segment, offset; 
int key, done = 0; 
char buffer[8000]; 
float a, b, result; 
void get video mode (int *; int .*, ant *); 
void memory map put (int, int, int); 
void buffer video region (int, int, int, int, int, char *); 
VOrd. put “float (Tloaty. Ant, inty int, Ine). ant) ani); 


void put string (char *, inty..int, int). 12nt,;21nt)? 


float get_prompted_float (float, int, int, int, int, int, 
inca Char *> Ant. ant. ane, char *>.“anty ane, any ane): 


attribute = 7; 


get_video mode (&width, é&mode, &current_page); 
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£¢ “Cewidth FS Boy. Ie ade S3)) 


return ; /* only support 80 column */ 
if (mode == 7) /* monochrome system */ 


{ 
segment = 0xB000; 
page = 0; 
} 
else 
segment = 0xB800; 


buffer screen region (page, 0, 24, 0, 79, buffer); 


upper row = 0; 

lower row = upper row + 14; 
leftmost_column = 0; 
rightmost_column = 79; 


/* clear the screen region to be used by the calculator */ 


for (i = upper row; i < lower row; i++) 
{ 
offset = (page * 4096) + (i * 160); 
for (j = leftmost_column; j <= rightmost column; jt+) 
memory map put (segment, offset + (j * 2) + 1, 0); 
} 


/* display the upper row of the frame */ 


offset = (page * 4096) + (upper row * 160); 

memory map put (segment, offset + (leftmost column * 2), 201); 

memory map put (segment, offset + (leftmost _column * 2) + 1, 
attribute) ; 

memory map put (segment, offset + (rightmost_column * 2), 187); 

memory map put (segment, offset + (rightmost column * 2) + 1, 
attribute); 


for (i = leftmost_column+l; i <= rightmost _column-1; ++) 

{ 
memory. map put (segment, offset + (i * 2), 205); 
memory map put (segment, offset + (i * 2) + 1, attribute); 


} 


/* display the lower row of the frame */ 


offset = (page * 4096) + (lower row * 160); 

memory map put (segment, offset + (leftmost _column * 2), 200); 

memory map put (segment, offset + (leftmost column * 2) + 1, 
- attribute); 


memory map put (segment, offset + (rightmost_column * 2), 188); 
memory map put (segment, offset + (rightmost _column * 2) + 1, 
. attribute) ; 


for (i = leftmost_columnti; i <= rightmost_column-1; i++) 
{ 
memory map put (segment, offset + (i * 2), 205); 
memory map put (segment, offset + (i * 2) + 1, attribute); 


} 
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put string ("Value:", page, 2, 4, attribute, 10); 
put string ("Value:", page, 4, 4, attribute, 10); 
put_string ("Result:", page, 6, 4, attribute, 10); 
put string ("F7 Addition F8 Subtraction", page, 
8, 4, attribute, 40); 
put_string ("F9 Multiplication F10 Divsion", page, 
9, 4, attribute, 40); 
a = ger. prompted float. (0, page, 2, 12, 
LOp “Te te. “Values: 25. 47. 10; 
"Enter first value,", 12, 4, 25, ° 7)3 
b = get_prompted float (0, page, 4, 12, 
LPOu. Ve. hp Varese <4 Asp As 
"Enter second value.", 12, 4, 25, 7); 
put_string ("Select function key desired ", 0, 12, 
A Ty BOY 4 
while (! done) 
{ 
key = no echo read(); 
if (key == 0) /* need a function key */ 
{ 
key = no echo read (); 
if (key == 65) ja See 
{ 
result = a+b; 
done = 1; 
} 
else if (key == 66) /* F8 */ 
{ 
result =a - b; 
done = 1; 
else if (key == 67) /* FQ */ 
{ 
result = a * b; 
done = 1; 
} 
else if (key == 68) /* F10 */ 
1 
result =a // b; 
done = 1; 
} 
} 
} 
put_ float (result, page, 6, 12, 7, 20, 5); 
put string ("Press any key to continue Mes Oy. AEP, 
A, Wa 30y3 
key = no_ echo read (); 
if (key == 0) no echo read (); /* read second half of 


restore screen region 


return (result); 


} 


(page, 0, 


special or function key */ 


24, 04. Fy 


buffer); 
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Menus and video pop-up menus can be used effectively to control 
the user interface. The routines in this chapter are meant to provide 
you with the foundation from which you can develop more powerful 
routines in the future. 


ASCII Codes 


Table A-1 lists the ASCII codes for characters. 


Table A-1. 


DEC OCTAL HEX ASCII 


<a) 


Connor wohr 


000 
001 
002 
003 
004 
005 
006 
007 
010 
O11 


ASCII Character Codes 


DEC OCTAL HEX 


012 
013 
014 
015 
016 
O17 
020 
021 
022 
023 


ASCII 
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Table A-1. ASCII Character Codes (continued) 


DEC OCTAL HEX ASCII DEC OCTAL HEX ASCII 
20 024 +14 + «9DC4 64 100 40 
21 025 15 £NAK 6 101 41 
22 026 16 SYN 66 102 42 
23 027 #2117. 4-ETB 67 103 48 
24 030 418 # #CAN 68 104 44 
25 031 19 4-EM 69 105 45 
26 032 1A SUB 70 106 46 
27 ~=°088—'—«1BBs-sdéE&ESCC 71 10747 
28 034 #+1C FS 72 110 48 
29 035 1D GS 73 lll 49 
30 036 IE RS 74 112 4A 
31 037 #\1F US 75 113 4B 
32 040 20 SPACE 76 114 = 4C 
33. 041s ! 77 115 4D 
34 042—t—s«i2D ‘ 78 116 4E 


85 = 048.8 i - 79 117 4F 
36 «044.—s 24 $ 80 120 50 
87 045 «25 81 121 51 
38 046 Ss 6 & 82 122 52 
39 047) 27 838 128 © 53 
40 050 28 84 124 54 
41 051 29 ) 85 125 55 
42 052 2A * 86 126 56 
43 053 2B - 87 127 57 


44 054 20.- , —— 688 130 o8 
45 055 2D = 89 131 o9 
46 056 2E 90 132 DA 


ZONK MES CHNDMOVOTZESORUHMDONMUAWPE 


60 O74 38C 
61 O75 3D 
62 076 3K 
63 O77 3F 


104 150 68 
105 151 69 
152 6A 
107 153 6B 


AT 057 2F / 91 133 5B 

48 060 30 0 92 134 5C 

49 061 ol 1 93 135 5D 

o0 062 32 2 94 136 = o56E 

ol 063 38 3 95 137. OF ae 

o2 064 34 4 96 140 60 

53s «065 30 D 97 141 61 a 

D4 066 36 6 98 142 62 b 

DO 067 Oo” 7 99 143 63 c 

56 070 38 8 100 144 64 d 

ov = (O71 39 9 101 = 145 65 e 

D8 072 3A (102 146 66 f 

D9 073 3B 103 147 67 g 
h 
i 
j 
k : 


OV IA” 
— 
one) 
o> 
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DEC OCTAL HEX ASCII 


108 
109 
110 
111 
112 
113 
114 
115 
116 
117 


154 
155 
156 
157 
160 
161 
162 
163 


164 


165 


ASCII Character Codes (continued) 


Set ee OS OS a 


DEC OCTAL HEX 


118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


166 
167 
170 
171 
172 
173 
174 
175 
176 
177 


ASCII CODES 


ASCII 


DEL 
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Turbo C 
Run-Time 
Library 


This appendix provides you with the calling sequence and function 
of each routine in the Turbo C run-time library. As stated earlier in 
this text, the goal of developing a complete library of routines is to 
reduce duplication of effort. As such, it is very important that you 
become familar with the Turbo C run-time library. 

As you will find, Borland provides you with a myriad of routines 
that you can use extensively within your applications. Take some 
time now to examine the Borland Turbo C run-time library. 
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void abort (void); 


ant 


Function Writes a termination message to stderr, aborting the 
current application by invoking —exit(3). 


Include File <stdlib.h> 


Example 


abort(); 


abs (int); 


Function § Returns the absolute value of the specified integer 
value. | | 


Include File <stdlib.h> 


Example 
result = abs (a * b); 
Note I[f you do not include stdlib.h, Turbo C will invoke abs as a 


macro, as opposed to a function. The abs routine will return a value 
in the range 0 to 32,767. 


ant absread (int disk, 
ant num—sectors, int first—sector, 


void *buffer); 


Function Reads a physical sector or sectors from disk into the 
specified buffer. | 
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Include File <dos.h> 


disk (in): Disk drive desired (A = 0, B = 1, C = 2) 
num_—sectors (in): Number of sectors to read 
first__sector (in): Starting sector number for read 
buffer (out): Buffer to read disk information into 


Example 


status = absread (0, 1, 0, boot__record); 


Note If successful, absread returns 0; otherwise, it returns —1. 


int abswrite (int disk, 
ant num—sectors, int first—sector, 
void *buffer); 


Function Writes a physical sector or sectors from disk to the 
specified buffer. 


Include File <dos.h> 


disk (in): Disk drive desired (A = 0, B = 1, C = 2) 

num_sectors (in): | Number of sectors to write 

first__sector (in): Starting sector number for write 

buffer (out): Buffer to write disk information from 
Example 


status = abswrite (0, 1, 0, boot—record); 


Note If successful, abswrite returns 0; otherwise, it returns —1. 
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ant access (char *filename, 
ant access—mode); 


Function Determines if the specified file exists, and if so, how 
the file can be accessed. 
Include File <io.h> 


filename (in): File desired 
access__mode (in): Bit pattern specifying the mode of. 
access desired: 
0 File existence 1 Executable 
2 Writeable 4 Readable 
6 Read/write access 


Example 


status = access (“TURBO.NTS”, 0); 


Note If the access mode is valid for the specified file, access 
returns the value 0; otherwise, it returns —1. 


double acos (double); 


Function Returns the are cosine of the specified expression. 
Include File <math.h> 


Example 


result = acos (pi); 
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int alloemem (unsigned paragraphs, 
unsigned *segment—address); 


Function Allocates a DOS memory segment. 


Include File <dos.h> 


paragraphs (in): Number of 16-byte paragraphs 
desired 
segment_address (in): | Pointer to the segment address 
returned 
Example 


status = alloemem (1000, &seg—addr); 


Note If successful, alloemem returns the value —1; otherwise, it 
returns the size of the largest available block. You should not use this 
function with malloc or calloc, farmalloc or faralloc. 


void far are (int «loc, int yloc, 
ant start—angle, 
ant end—angle, int radius); 


Function Draws a circular arc at the specified x,y location, 
using the starting and ending angles provided. 
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Include File <graphics.h> 


xloc, yloc (in): Specifies the center of the arc 
start__angle (in): Starting angle for the are (0-360) 
end_angle (in): = Ending angle for the arc (0-360) 
radius (in): Radius of the arc 

Example 


arc (100, 200, 0, 360, 10); 


Note The arc routine uses the current drawing color. 


char *asctime (struct tm *time); 


Function Converts a date and time to its ASCII representation. 
Include File <time.h> 


Example 


_ time_string = asctime (&current—datetime); 


double asin (double); 


Function Returns the arc sine of the specified expression. 
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Include File <math.h> 


Example 


result = asin 


void assert (int condition); 


Function Tests the specified condition. If the test fails, assert termin- 
ates the current program and displays the message 


Assertion failed: file PROGRAM, line LINE._NUMBER 


Include File <assert.h> 


condition (in): Boolean expression to test 


Example 


assert(arge > 1); 


Note If you set the NDEBUG directive to no debugging prior to 
an assert, Turbo C will ignore the assert. 


double atan (double); 


Function Returns the arc tangent of the specified expression. 
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Include File <math.h> 


Example 


result = atan (pi) 


double atan2 (double, double); 


Function Returns the arc tangent of x and y expressions. 
Include File <math.h> 


Example 


result = atan2 (y, x); 


int atexit (atexit—t function—name); 


Function Defines a function that Turbo C will invoke (without 
arguments) at program termination prior to returning control to the 
operating system. 


Include File <stdlib.h> 


function__name (in): Entry point of function to add to 
exit list 


Example 


void test () 
{ 
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printf ("Test called \n”); 
j 


main () 


status = atexit (test); 


Note If successful, atexit returns the value 0. If an error occurs, 
atexit returns a nonzero value. 


double atof (char *str); 


Function Converts an ASCII string representation of a value to 
a floating-point value. 


Include File <math.h> 


str (in): ASCII representation of value 


Example 


salary = atof ("77500.34”); 


Note If the string cannot be converted, atof returns 0. 


wnt ator (char *str); 


Function Converts a string representation of an integer value to 
a value of type int. 


™ 
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Include File <stdlib.h> 


gtr (in): | ASCII representation of the value 


Example 


age = atoi ("59"); 


Note If the string cannot be converted, atoi returns 0. 


long atol (char *str); 


Function Converts an ASCII representation of a value to a value 
of type long int. | 


Include File <stdlib.h> 


Example 


zip—code = atol (’89126”); 


Note If the string cannot be converted, atol returns the value 0. 
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void far bar (int left—corner, 
wnt top—corner, int right— corner, 
wnt bottom—corner); 


Function Draws a bar (for a bar graph) with the specified 
corners. 


Include File <graphics.h> 


left__corner (in): Specifies the x coordinate of the 
upper-left corner 

top—corner (in): Specifies the y coordinate of the 
upper-left corner 

bottom —corner (in): Specifies the y coordinate of the 
lower-right corner 

right—corner (in): Specifies the x coordinate of the 


lower-right corner 


Example 


bar (10, 10, sales, offset); 


Note The bar routine uses the current fill pattern and color. 


void far bar3d (int left—corner, 
ant top—corner, int right—corner, 
int bottom—corner, int depth, 

wnt top—flag); 


Function Draws a bar (for a bar graph) with the specified 
corners. 
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Include File <graphics.h> 


left__corner (in): Specifies the x coordinate of the 
upper-left corner 

top—corner (in): Specifies the y coordinate of the 
upper-left corner 

bottom—corner (in): Specifies the y coordinate of the 

| lower-right corner 

right__corner (in): Specifies the x coordinate of the 
lower-right corner 

depth (in): Depth of the bar in pixels 

top_—_tflag (in): If 0, the bar is not drawn in 3D. If 


nonzero, the number of pixels speci- 
fied by depth are added to the bar 


Example 


bar3d (10, 10, sales, offset,3, 1); 


Note The bar3d routine uses the current fill pattern and color. — 


wnt bdos (int DOSfunction, 
unsigned dx, unsigned al); 


Function Invokes a DOS function (small memory model) that 
only requires the DX and AX registers. 


Include File <dos.h> 


DOSfunction (in): DOS service to be performed 


dx (in): DX register contents for service 
al (in): AL register contents for service . 
Example 


current_drive = bdos (0X19, Q, 0); 


ang 
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Note The bdos routine returns the contents of the AX register or 
the value —1 if an error occurs. 


unt bdosptr int DOSfunetion, void *parameter, 
unsigned al); 


Function Invokes a DOS function that requires a pointer to an 
argument and AX registers. 


Include File <dos.h> 


DOSfunction (in): DOS service to perform 


parameter (in): Parameter required for the service 
al (in): AL register contents for service 
Example 


current—drive = bdosptr (0X19, 0, 0); 


Note The bdosptr routine returns the contents of the AX regis- 
ter or the value —1 if an error occurs. 


wnt bioscom (int command, 
char byte, int port—id); 


Function Performs serial I/O through the specified port. 
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Include File <bios.h> 


command (in): Operation to perform: 
0 Set port 1 Send character 
: 2 Receive char 3 Return status 
byte (in): Port settings or char to output 
port—id (in): Serial port ID (0-com1, 1-com2) 
Example 


status = bioscom (1, 65, 0); 


Note Refer to bios.h for more specifics on port settings. 


wnt briosdisk (int command, - 
wt disk, int side, int track, © 
ant sector, int numsectors, 
void *buffer); 


Function Performs disk operations by means of BIOS interrupt 
13H. | 


Include File <bios.h> 


command (in): Disk operation to perform: 
Resets disk system 
1 Returns last operation status 
2 Reads sector(s) 
3 Writes sector(s) 
4 Verifies sector(s) 
5 Formats track 
(AT and XT Services) 
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6 Formats track set bad sector 
flags 

fi Formats drive 

8 Returns disk drive parameters 

9 Initializes drive parameters 


OxA Long read operation 
0xB Long write operation 
0OxC Disk seek 

0OxD Alternate disk reset 
OxE Reads sector buffer 
OxF Writes sector buffer 
0x10 Test drive ready 
Oxll  Recalibrates drive 
0x12 Controller diagnostic 
0x18 Drive diagnostic 
0x14 Controller internal diagnostic 


disk (in): Disk drive desired (A = 0, B = 1, C = 2) 
side (in): Side of disk desired (0 or 1) 

track (in): Track desired 

sector (in): Starting sector for operations 


numsectors (in): Number of sectors to manipulate 
buffer (in/out): | Data buffer for operations 


Example 


status = biosdisk (2, 0, 0, 0, 0, 1, bootrecord); 


Note If the operation is successful, 0 is returned. Otherwise, 
biosdisk returns an error status value. 


wnt biosequip (void); 


Function Returns a value specifying the current equipment 
connections. 


Include File <bios.h> 
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Example 


equipment = biosequip (); 


Note The integer value returned specifies the following: 


Bit 1 Math coprocessor present 

Bits 2-3 Motherboard RAM (0=16K, 1=382K, 
2=48K, 3=64K) 

Bits 4-5 Video mode (0=n/a, 1=40X25 color, 
2=80X25 color, 8=80X25 bw) 

Bits 6-7 Number of diskettes (O=1 drive, 1=2 
drives, 2=3 drives, 3=4 drives) 

Bit 11 Number of serial ports 

Bit 12 Game adapter present 

Bits 14-15 Number of printers present 


int bioskey (int command); 


Function Provides an interface for BIOS keyboard services. 


Include File <bios.h> 


command (in): Operation to perform: 

returns the next key pressed. If the 
lower byte is 0, the upper byte con- 
tains the scan code for the key 
pressed 

1 returns the next key in the buffer if 
a keystroke is available; otherwise, 
returns the value 0 

2 returns the current keyboard status: 
Oxl Right SHIFT key pressed 
0x2 Left SHIFT key pressed 
0x4 CTRL key pressed 
0x8 ALT key pressed 
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0x10 SCROLL LOCK on 
0x20 NUM LOCK on 
0x40 CAPS LOCK on 
0x80 INS On 


Example 


status = bioskey (2); 


wt biosmemory (void); 


Function Returns the amount of system memory in kilobytes. 
Include File <bios.h> 


Example 


Kbytes = biosmemory (); 


wnt biosprint (inc command, 
wnt byte, int port—id); 


Function BIOS printer interface routine. 


Include File <bios.h> 


command (in): Command to perform: 
0 prints the character in bytes 
1 initializes the specified printer port 
2 returns the printer status 
byte (in): Character to be printed for command 1 
port—id (in): Port number affected (0-LPT1, 1-LPT2) 
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Example 


status = biosprint (1, 65, 0); 


Note Valid return status values include the following: 


0x01 Device time out 0x08 Output error 
0x10 Printer selected 0x20 Printer out of paper © 
0x40 Ack 0x80 Printer not busy 


long biostime (int command, 
long new—realtime); 


Function Sets or returns the current system real-time clock 
counts. 


Include File <bios.h> 


command (in): Command to perform (0 returns 
current count, 1 sets current count) 
new realtime (in): | Clock ticks since midnight 
Example 


count = biostime (0, dummy); 


Note The real-time clock on the IBM PC and PC compatibles 
ticks 18.2 times per second. This routine returns the number of clock 
ticks since midnight. 
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wnt brk (void *end—datasegment); 


Function Modifies the data segment space allocation. 


Include File <alloc.h> 


end__datasegment (in): The new desired end of the data 
segment 


Example 


status = brk (endds); 


Note The memory location that immediately follows the data 
segment is called the break value. By modifying this value you can 
resize the application’s data segment size. 


void *bsearch (void *key, 
void *base, int number—of —elements, 
unt width, wnt (*compare—function)()); 


Function Performs a binary search to locate a specific element 
in an array. 


Include File <stdlib.h> 


key (in): The search key of the desired 
item 
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base (in): Pointer to element 0 of the 
array | 

number_—of_—_elements (in): Number of elements in the 
array 

width (in): Size of each entry in bytes 

compare—function (in): Function to perform element 


Return &@ value <0ifa<b comparisons 
Return a value = 0a=b 
Return a value > 0ifa>b 


Example 
index = bsearch (ssan, social, 100, 2, comp); 


Note If the element is not found, bsearch returns the value 0. 


double cabs (struct complex number); 


Function Returns the absolute value of a complex number. 


Include File <math.h> 


number (in): Complex number desired 


Example 


result = cabs (complex); 
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void *calloe (size—t number —of—elements, 
size—t element—size); 


Function Allocates a contiguous block of memory and initializes 
it to zero. 


Include File <stdlib.h>, <alloc.h> 


number__of__elements (in): Number of elements to al- 
locate space for 
element_—size (in): Size of each element in 
bytes 
Example 


pointer = (char *) calloc (1, 255); 


double ceil (double); 


Function Rounds the value of a double expression up. 
Include File <math.h> 


Example 


max = ceil (value); 
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| char *egets (char *string); 


Function Reads a character string from the console device. 


Include File <conio.h> 


string (in/out): String to be read. Upon input, string[0] 

should contain the number of characters 
to read. Upon completion, the string will 
contain string[1], the number of characters 
read, or string[2], the first character 
read | 

Example 

egets (string); 


Note The cgets routine replaces the newline character with the 
null character. | 


wt chdir (char *pathname); 


Function Selects the specified current directory. 
Include File <dir.h> 


Example 


status = chdir (”\\TURBOC”); | 
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Note If successful, chdir returns the value 0. If an error occurs, 
it returns the value —1. 


int —chmod (char *filename, 
unt function[, int attribute }); 


Function Sets or returns the attributes for a file. 


Include File <io.h> 


filename (in): Name of the desired file 

function (in): If 0, the current attribute is re- 
turned; if 1, the current attribute 
is set 

attribute (in): Desired file attribute: 
FA_RDONLY 
FA—HIDDEN 
FA_SYSTEM 

Example 


attribute = —chmod ("ALLOC.H”, 0); 


Note If successful, chmod returns the value 0. If an error occurs, 
the routine returns —1. 


int chmod (char «filename, 
ant access); 


Function Modifies the file access restrictions for the specified 
file. 
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Include File <io.h> 


filename (in): Name of the desired file 


access (in): File access desired: 
S_IWRITE Write access 
S_IREAD Read access 


S_IREAD | S_IWRITE Read/write access 


Example 


result = chmod ("“TEST.C”, S_IWRITE); 


Note If the routine is successful, chmod returns the value 0. If 
an error occurs, the routine returns —1. 


ant chsize (int file—handle, 
long new—size); 


Function Sets the size attribute for a file as specified. 


Include File <io.h> 


handle (in): File handle associated with the file 
a whose size is being set 
new__size (in): Desired size of the file in bytes 
Example 


result = chsize (file—handle, 32000); 


Note The file must be opened in either write or read/write 


-mode. 
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void far circle (int xloe, 
ant yloc, ant radius); 


Function Draws a circle at the specified x and y location. 


Include File <graphics.h> 


xloc, yloc (in): The x and y locations of the center of 
the circle 
radius (in): Desired size of the circle’s radius 
Example 


circle (100, 100, 10); 


Note The circle routine uses the current drawing color. 


unsigned int —clears7 (void); 


Function Clears the math coprocessor floating-point status word. 


Include File <dfloat.h> 


Example 


status = —clear87(); 


Note The value returned by —clear87 contains the previous sta- 
tus word. 
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void far cleardevice (void); 


Function Clears the screen display in graphics mode. 
Include File <graphics.h> 


Example 


cleardevice( ); 


Note The cleardevice routine erases the entire graphics screen 
and updates the current position to 0,0. 


void clearerr (FILE *file—pointer); 
Function Clears a file’s (stream’s) error status indicator. 


Include File <stdio.h> 


file__pointer (in): | Data stream desired 


Example 


clearerr (file—pointer); 


Note This service is closely related to ferror. 
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void far clearviewport (void); 


Function Clears the current viewport in graphics mode. 


Example 
clearviewport (); 


Note The clearviewport routine erases the current viewport and 
updates the current position to 0,0. 


mt —close (int file—handle); 
Function Closes the file associated with the given file handle. 


Include File <jo.h> 


file_handle (in): File handle of the file to close 


Example 
status = —close (file—_handle); 
Note If successful, —close returns the value 0; otherwise, it 


returns the value —1. Unlike close, close does not place an end-of- 
file marker (“Z) at the end of the file. 


wnt close (int file—handle); 
Function Closes the file associated with the given file handle. 


Include File <io.h> 


file_handle (in); File handle of the file to close 


Example 


status = close (file—handle); 


Note If successful, close returns the value 0; otherwise, it 
returns the value —1. The —close routine is a text file manipulation 
routine. Upon invocation, this routine places a “Z end-of-file marker 
at the end of the file. 


void far closegraph (void); 


Function Turns off graphics, returning you to text mode. 
Include File <graphics.h> 


Note The closegraph routine performs the inverse function of 
initgraph. 


void clreol (void); 


Function Clears text from the current cursor position to the end 
of the current line for the current text window. 
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Include File <conio.h> 


Example 


clreol(); 


Note The clreol routine does not move the current cursor 
position. 


void elrser(); 


Function Clears the current text window and places the cursor 
in the upper-left corner of the window (1,1). 


Include File <conio.h> 


Example 


elrser(); 


unsigned coreleft (void); 


Function Returns the number of bytes of core memory that are 
currently unused. 


Include File <alloc.h> 


Example 


bytes = coreleft (); 


Note For the compact, large, and huge memory models, use a 
return type of unsigned long. 


double cos (double); 


Function Returns the cosine of the specified double expression. 
Include File <math.h> 


Example 


result = double (pi); 


double cosh (double); 


Function Returns the hyperbolic cosine of the given double ex- 
pression. 


Include File <math.h> 
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Example 


result = double (p1); 


struct country *country—info (int country—code, 
struct country *country—info); 


Function Returns country-specific information. 


Include File <dos.h> 


country_—_code (in): Country code number of the desired 
country 

country_—info (out): Structure containing country infor- 
mation 


Note The DOS.H file defines the country structure. — 


wnt eprintf (char *format— 
string [, parameterf, . . .]}); 


Function Sends formatted output to the BIOS or video RAM. 
Include File <conio.h> 


format—string (in): String specifying the output format 
parameter (in): Data to be output 
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Example 
eprintf ("String %s Number %d \n”, str, 10); 
Note This routine does not expand newline characters into a 


carriage return/linefeed. This routine writes its output to the cur- 
rent window. 


void cputs (char *string); 
Function Writes a character string to BIOS or video RAM. 


Include File <conio.h> 


string (in): Character string to display 


Example 
cputs ("This is a test string \n”); 


Note The cputs routine does not append a newline character. 
This routine writes its output to the current window. 


wnt —creat (char *filename, 
mt attribute); 


Function Creates a file with the specified name and attribute. 
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Include File <dos.h> 


filename (in): Filename to create 
attribute (in): Desired file attribute 
Example 


result = —creat ("“TEST.DAT”, 0); 


Note Ifa file with the specified name exists, —creat overwrites it 
if the write attribute is set. If successful, —creat returns a file han- 
dle to the desired file; otherwise, it returns the value —1. 


unt creat (char *filename, 
ant access); 


Function Creates a file with the specified name and access. 


Include File <sys \stat.h> 


filename (in): Filename to create 
access (in): File access: 
S—IWRITE Write access 
S—_IREAD Read access 
S—IWRITE | S_IREAD ~ Read/write 
access 
Example 


result = creat (“TEST.DAT”’, S_IWRITE); 
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Note If a file with the specified name exists, creat overwrites it. If 
successful, creat returns a file handle to the desired file; otherwise, 
it returns the value —1. | | 


wnt creatnew (char *filename, 
wnt attribute); 


Function Creates a file with the specified name and attribute. 


Include File <jo.h> | 


filename (in): Filename to create 
attribute (in): Desired file attribute 
Example 


result = creatnew ("TEST.DAT”, 0); 


Note If a file with the specified name exists, creatnew overwrites 
it. If successful, creatnew returns a file handle to the desired file; 
otherwise, it returns the value —1. 


ant creattemp (char *filename, 
ant attribute); 


Function Creates a temporary file with the specified path given 
in filename and attribute. 
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Include File <io.h> 
filename (in/out): Path in which to create temporary file 
attribute (in): Desired file attribute 

Example 


result = creattemp ("TEST.DAT”, 0); 


Note If successful, creattemp returns a file handle to the desired 
file; otherwise, it returns the value —1. 


wnt escanf (char *format— 
sequence [, arguments }); 


Function Performs formatted input to the console device in a 
manner similar to scanf. 


format__sequence (in): Specifies the input format desired 
arguments (in): Pointers to the variables to be 
input 
Example 
num_—_tfields = escanf ("%d %d”", &valuel, &value2); 


Note The cscanf routine returns the number of input fields suc- 
cessfully scanned and stored. 


eS 
a 
fm) 
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char *ctime (long *seconds | 
—since—O1 —01—1970); 


Function Returns a string that corresponds to the specified date. 


Include File <timeh> | 
seconds__since__01__01__1970 (in): Number of seconds 
since 00:00 Jan 1, 1970 
Example 


printf ("Date %s \n”, ctime (&seconds)); 


Note The Turbo C routine time returns the number of seconds 
since 01/01/1970 for the current date. 


void ctrlbrk (int (*function)(void)); 


Function Defines a control-break handler. 


Include File <dos.h> 


_ function (in): Address of the function DOS will 
execute each time interrupt 23H 
occurs. This interrupt occurs when- 
ever the user presses CTRL-C or 
CTRL-BREAK. 
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Example 
int my—handler (); 
etrlbrk (my—handler); 


Note Upon program termination, DOS resets the interrupt 23H 
handler to its original value. 


void delay (unsigned milliseconds); 


Function Temporarily suspends processing for the specified 
duration. 


Include File <dos.h> 


milliseconds (in): Number of milliseconds to delay for 


Example 


delay (1000); /* delay 1 second */ 


void delline (void); 


Function Deletes the line containing the cursor in the current 
window, and scrolls all of the lines below the current line up one 
line. 


Include File <conio.h> 


Example 


delline(); 


void far detectgraph (int far *graph—driver, 
ant far *graph—mode); 


Function Returns the graphics driver and mode to be used with 
the current hardware. 


Include File <graphics.h> 


graph_driver (out): | Graphics driver to use for current 


hardware 
graph__mode (out): Graphics mode to use for current 
hardware 
Example 


detectgraph (&graph—driver, &graph—mode); 


double difftume (tume—t time2, 
tume—t time1); 


Function Returns the number of seconds by which the two speci- 
fied times differ. 
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Include File <time.h> 


time2 (in): Time to subtract timel from 
timel (in): Time subtracted from time2 to yield the 
difference in seconds 


Example 


result = difftime (today, yesterday); 


void disable (void); 


Function Disables hardware interrupts (with the exception of unmask- 
able interrupts). 


Include File <dos.h> 


Example 


disable(); 


Note To reenable interrupts, you must use the enable routine. 


div—t dw (int numerator, 
ant denominator); 


Function Performs integer division, returning both a quotient 
and a remainder. 
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Include File <stdlib.h> 


numerator (in): Number to be divided 
- denominator (in): | Number divided into the numerator 
Example 


result = div (16, 3); 


Note div__t is a structure containing 


typedef struct { 
int quot; 
int rem; 

1 div__t; 


nt dosexterr (struct DOSERR *error—info); 


Function Fills the structure pointed to by error—info with the 
extended error information for the last failing DOS system service. 
Include File <dos.h> 


error—info (out): Structure to contain extended error 
information 


Example 


result = dosexterr (error —info); 
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Note If dosexterr returns the value 0, the previous DOS system 
service did not experience an error. 


long dostounix (struct date *date—ptr, 
struct tume *time—ptr); 


Function Converts the DOS date and time format into a UNIX 
date and time format. 


Include File <dos.h> 


date__ptr (in): Structure containing the current 
DOS date 
time—ptr (in): Structure containing the current 
DOS time 
Example 


unix__time = dostounix (&date—var, &time—var); 


void far drawpoly (int number—of—porints, 
ant far *points); 


Function Draws the outline of the polygon contained in the 
points array. 


rue rT 
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Include File <graphics.h> 


number__of__points (in): Number of points in the polygon 
points (in): Array containing the x,y coor- 
: dinates of the polygon 


Example 


drawpoly (4, triangle); 


Note If an error occurs in drawpoly, graphresult will contain 
—6. | 


ant dup (wnt file—handle); 
Function Duplicates a DOS file handle. 


Include File <jo.h> 


file—_handle (in): File handle to duplicate 


7 Example 


new—_handle = dup (file—handle); 


Note If dup is successful, it returns a positive file handle. Oth- 
erwise, dup returns a negative value. 
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int dup2 (int old—file—handle, 
nt new—file—handle); 
Function Duplicates a DOS file handle. 


Include File <io.h> 


old__file__handle (in): File handle to duplicate 
new —_file__handle (in): New copy of file handle 
Example 


dup (oldfile, filehandle); 


Note This routine is provided for compatibility with UNIX. 


char *ecvt (double value, 

unt number—of—digits, 

unt *decumal—loe, int *sign); 
Function Converts a floating-point number into a character 
string. 


Include File <stdlib.h> 


value (in): Floating-point value to con- 
vert 

number__of_—digits (in): Number of digits in the 
string representation of the 
value 


A477 
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decimal__loc (out): Location of the decimal point 
sign (out): Negative value if the value is 
nonzero; 0 otherwise 


Example 


str = ecvt (664.333, 7, &loc, &sign); 


Note This routine does not place the decimal into the string or 
place a negative sign at the front of the string. 


void far ellipse (int x—loc, 

ant y—loc, int start—angle, 

ant end—angle, 

nt x—radius, wnt y—radius); 
Function Draws an ellipse, at the given location, with the aspect 
ratio specified by x__radius and y_radius. 


Include File <graphics.h> 


x_—loc, y—loe (in): The x and y locations of the center of the 
ellipse 
start_angle (in): Starting angle for the ellipse 
end__angle (in): End angle for the ellipse 
X__radius (in): Radius of the ellipse along the x axis 
y—radius (in): Radius of the ellipse along the y axis 
Example 


ellipse (100, 100, 0, 360, 10, 5); 
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Note The ellipse routine uses the current drawing color. 


void enable (void); 


Function Enables interrupts previously disabled by the run-time 
library disable routine. 


Include File <dos.h> 


Example 


enable(); 


Note The disable routine can only disable unmaskable interrupts. 


wnt eof (int file—handle); 


Function Returns true if the file associated with the given file 
handle has reached end of file; otherwise, eof returns the value 0. 


Include File <io.h> 


Example 


while (! eof (file—handle)) 


Note If eof experiences an error, it returns the value —1. 
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unt exec .. . (char *path, 
char *arg0, char *arg1 ..., 
NULL); 


Function Spawns a DOS command as a child process. 


Include File <process.h> 


path (in): Name of the command to spawn 
arg(Q-aren: Command-line parameters for the 
spawned program 


Example 


status = execl ("TEST.EXE”, "TEST.EXE”, "A1”, NULL); 


Note The execl routine is similar to exec but only searches the root 
or current directory for the child. If you add the suffix "p,” it will 
search for the child program in the directories contained in the DOS 
path. If you add the suffix “1,” you pass the command-line parame- 
ters as individual values. If you add "v,” you are passing the — 
command-line parameters as an array of pointers. Lastly, the “e” 
suffix allows you to pass an environment to the child process. If no 
environment is specified, the child inherits the current environment. 


void —exit (int status); 


Function Terminates the current program, returning the speci- 
fied status value. 
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Include File <process.h> 


status (in): Status value to return to the parent process 
or DOS 
Example 
—exit (0); 


Note The —exit routine does not close open files. 


void exit (int status); 


Function Terminates the current program, returning the speci- 
fied status value. 


Include File <process.h> 


status (in): Status value to return to the parent 
process or DOS 


Example 


exit (0); 


Note The exit routine flushes file buffers and appropriately 
- updates files. 


double exp (double value); 


Function Returns the exponential of the specified value. — 


Include File <math.h> 


value (in): Value to return the exponential of 


Example 


result = exp (x); 


double fabs (double value); 


Function Returns the absolute value of a-double-precision 
expression. 


Include File <math.h> 


value (in): Value to return the absolute value of 


Example 


result = fabs (—44.3332); 


void far *farcalloc (unsigned long number 
—of—entries, 
unsigned long entry —size); 


Function Allocates memory from the far heap and clears it. 
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Include File <alloc.h> 


number_—of_—entries (in): Number of elements to allocate 
space for 

entry __size (in): Number of bytes in each 
element 


Example 


chunk = faralloce (1, 65000); 


Note If faralloc cannot allocate the specified space, it returns the 
value NULL. 


long farcoreleft (void); 


Function Returns the number of bytes available in the far heap. 
Include File <alloc.h> 


Example 


long__var = farcoreleft (); 


void farfree (void far *ptr); 


Function Returns previously allocated memory to the far heap. 


Include File <alloc.h> 
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Example 


farfree (chunk); 


void far *farmalloc (unsigned long number 
—of —bytes); 


Function Allocates space from the far heap. 


~ Include File <alloc.h> 
number_—_of_bytes (in): Number of bytes of memory to 
allocate 
Example 
buffer = farmalloc (65000); 


Note If farmalloc cannot satisfy the request, it returns the value 
NULL; otherwise, it returns a pointer to the desired memory. 


void far *farrealloc (void far *ptr, 
unsigned long num—bytes); 


Function Reallocates memory for a previously allocated segment 
of memory from the far heap. 
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Include File <alloe.h> 


ptr (in): Pointer to the previously allocated 
memory 
num_bytes (in): Number of bytes of memory desired 


Example 


block = farrealloc (block, 65001); 


int felose (FILE *stream); 


Function Flushes all of the buffers associated with a file and 
updates the file on disk. 


Include File <stdio.h> 


Example 


status = fclose (file); 


Note If successful, felose returns the value 0. 


wnt feloseall (void); 


Function Flushes all of the buffers associated with open files and 
updates each file on disk as it closes it. | 
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Include File <stdio.h> 


Example 


status = fcloseall (); 


Note This routine returns the number of file streams closed. 


char *fcevt (double value, 

ant number —of —digits, 

ant *decimal—loe, int *sign); 
Function Converts a floating-point number into a character 
string. 


Include File <stdlib.h> © 


value (in): Floating-point value to convert 

number_of_—digits (in): Number of digits in the string 
representation of the value 

decimal_—_loc (out): Location of the decimal point 

sign (out): | Negative value if the value is 
negative; 0 otherwise 


Example | 

str = ecvt (664.333, 7, &loc, &sign); 

Note This routine does not place the decimal into the string or 
place a negative sign at the front of the string. This routine differs 


from ecvt in that it rounds to FORTRAN F format the number of | 
digits specified. | 
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FILE *fdopen (int handle, 
char *open—type); 


Function Associates a stream with the file handle returned by 
creat, dup, dup2, or open. 


Include File <stdio.h> 


handle (in): File handle to associate with the stream 
open__type (in): Specifies how the file can be accessed: 
r Read-only w Write access 
a Append r+ Read/write 
w+ Create new at+ Create for ap- 


pend if no file 


Example 


file—pointer = fdopen (handle, "r”); 


Note If an error occurs, fdopen returns the value NULL. 


wnt feof (FILE *stream); 


Function Returns true (1) if the specified file has reached end of 
file; otherwise, returns 0. 


Include File <stdio.h> 


stream (in): File stream to examine for end of file 


Example 


while (! feof (in—_file)) 
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wnt ferror (FILE *stream); 


Function Returns true (1) if the specified file experienced a read 
or write error; otherwise, returns 0. 


Include File <stdio.h> 


stream (in): File stream to examine for error 


Example 


status = ferror (in—file); 


int fflush (FILE *stream); 
Function Flushes the file buffers for the specified file. 


Include File <stdio.h> 


Example 


status = fflush (in_file); 


Note If the file is an input file, fflush flushes the input stream. 


wnt fgete (FILE *stream); 


Function Reads the next character from the specified file 
stream. 
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Include File <stdio.h> 


Example 
ltr = fgetc(in—file); 


Note If fgetc obtains EOF or an error occurs, it will return the 
value EOF. 


int fgetchar (void); 


Function Reads the next character from stdin. 
Include File <stdio.h> 


Example 


ltr = fgetchar; 


Note If fgetchar obtains EOF or an error occurs, it will return the 
value EOF. Unlike getchar, fgetchar is a function. 


ant fgetpos (FILE *file—stream, 
fpos—t *file—position); 


Function Stores the current file position of the file associated with 
file_stream into the location pointed to by file—position. 
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Include File <stdio.h> 


file_stream (in): File pointer associated with the 
file of interest | 
file__position (out): Location at which current file posi- 


tion is stored 


Example 


status = fgetpos (fp, &file—position)); 


Note If successful, fgetpos returns 0; otherwise, it returns a non- 
zero value. 


char *fgets (char *string, 
ant num—bytes, FILE *stream); 


Function Reads a character string from an input stream. 


Include File <stdio.h> 


string (out): Character string of data read . 
num__bytes (in): Maximum number of characters in the 
| string | 
stream (in): File stream to read the characters from 
Example 


status = fgets (str, 255, fp); 


TURBO C RUN-TIME LIBRARY 491 


Note Upon end of file, fgets returns NULL. It leaves the newline 
character at the end of each string. 


long filelength (int file—handle); 


Function Returns the number of bytes in the file associated with 
the given file handle. 


Include File <io.h> 
file_handle (in): File handle returned from open or 


creat 


Example 


long—var = filelength (handle); 


Note If filelength encounters an error, it returns the value —1L. 


wnt fileno (FILE *stream); 


Function Obtains a file handle for a given file stream. 


Include File <stdio.h> 


stream (in): File stream to return a file handle to 
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Example 


file_handle = fileno (fp); 


void far fillpoly (int number — 
of —points, int far *points); 


Function Draws the outline for, and fills in, the polygon specified 
in the points array. 


Include File <graphics.h> 


number_—of—points (in): Number of points in the polygon 
points (in): Array of points specifying the 
polygon’s shape | 


Example 


fillpoly (10, points); 


Note The fillpoly routine uses the current drawing and fill colors 
and fill pattern. 


unt findfirst (char *path, 
struct ffblk ——- 
wnt attribute); 


Function Searches a directory of files for a file that matches the 
given description (filename or wildcard characters). 
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Include File <dir.h> 


path (in): DOS pathname (including optional 
drive) of the path to examine in search of 
the files 

fileblock (out): File block structure containing 
struct ffblk { 


char ff__reserved[21]; 
char ff__attrib; 

int ff__ftime; 

int ff__fdate; 

long  ff__fsize; 

char ff—name[13]; 


attribute (in): File attribute to be used in matching 
files 


Example 


status = findfirst ("*.*”, &file—block, 0); 


Note Use findfirst to locate the first matching file and the findnext 
routine to locate subsequent files. If findfirst is successful, it returns 
the value 0. 


ant findnext (struct ffblk *fileblock),; 


Function Searches a directory of files for a file that matches the 
description (filename or wildcard characters) given in a call to 
findfirst. 


Include File <dir.h> 


fileblock (out): File block structure as defined in find- 
first 


Example 


status = findnext (&file—block); 


Note Use findfirst to locate the first matching file and the findnext 
routine to locate subsequent files. If successful, the findfirst routine 
returns the value 0. 


void far floodfill (int x—loe, 
wnt y—loc, int border—color); 


Function Fills a region bounded by the color specified in border— 
color with the current fill pattern and color. 


Include File <graphics.h> 


x—loe (in): The x point that resides within the region — 
to fill 

y—loe (in): The y point that resides within the region 
to fill 


border_color: Color surrounding the region to fill 


Example 


floodfill (100, 100, red); 
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Note If floodfill encounters an error, graphresult will contain —7. 


double floor (double value); 


Function Rounds a double-precision value down to the largest in- 
teger that is not greater than the value. 


Include File <math.h> 


value (in): Double-precision value to round 


Example 


approx_——cost = floor (purchase—price * tax); 


wt flushall (void); 


Function Flushes all of the disk buffers for open file streams. 
Include File <stdio.h> 


| Note The flushall routine returns 0 upon success. 


double fmod (double x, double y); 


Function Returns the remainder of the division of two double- 
precision values. | 
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Include File <math.h> 


x (in): Value y is divided into 


y (in): The divisor 
Example 


result = fmod (total_sales, employees); 


Note See also the modf routine. 


void frmerge (char *path, 
char *drive, char *directory, 
char *filename, char *extension); 


Function Builds a complete DOS pathname from all of the compo- 
nent parts. 7 


Include File <dir.h> 


path (out): Complete DOS pathname 

drive (in): Desired drive letter, including colon 

directory (in): DOS directory path desired 

filename (in): 8-character DOS filename 

extension (in): —3-character DOS file extension 
Example 


fnmerge (path, "A:”, "\\TURBOC\\"", “TEST”, "C”); 
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Note See also the fnsplit routine. 


void fnsplit (char *path, 
char *drive, char *directory, 
char *filename, 

char *extension); 


Function Breaks down a complete DOS pathname into all of its 
component parts. 


Include File <dir.h> 


path (out): Complete DOS pathname 

drive (in): Desired drive letter, including colon 

directory (in): DOS directory path 

filename (in): 8-character DOS filename 

extension (in): 3-character DOS file extension 
Example 


fnsplit (“A:\\TBO\\FILENAME.C”, drive, path, file, ext); 


Note See also the fnmerge routine. 


FILE *fopen (char filename, 
char *access—type); 


Function Opens a DOS file stream. 


Include File <stdio.h> 
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filename (in): Name of the file to open 
access__type (in): Defines how the file will be accessed: 
r Read-only w Write 
a Append r+ Read/write 
w+ Create write at Append create 
if new file 
Example 


fp = fopen (argv[1], "r”); 


Note If unsuccessful, fopen returns NULL. If you need to open a 
file in binary mode, simply attach a b to the access type, as in rb or 
wh. For text mode, you can append the letter t. | 


unsigned FP_OFF (void far *far—pointer); 


Function Returns the offset portion of a far pointer. 


Include File <dos.h> 


far_pointer (in): Far pointer to return the offset portion 
of 


Example 


offset = FP__OFF (far—pointer); 


void —fpreset (void); 


Function Reinitializes the floating-point math library. 
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Include File <dfloat.h> 


Note Early DOS versions (before version 2.x) allowed child pro- 
cesses to leave the 8087 in an inconsistent state. This routine resets 
the math coprocessor to a known state. 


nt fprintf (FILE *stream, 
char *format—sequence [, arguments .. . J); 


Function Performs formatted output to a file stream. 


Include File <stdio.h> 


stream (in): File stream to be written to 

format__sequence (in): Control sequence specifying the 
output format 

arguments (in): Data to be written to the file 


Example 


num_—bytes = fprintf (fp, “%d %f\n”, days, salary); 


Note The fprintf routine returns the number of bytes written to 
the data stream. 
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unsigned FP_SEG(void far 
*far—porinter); — 


Function’ Returns the segment portion of a far pointer. 


Include File <dos.h> 


far__pointer (in): Far pointer to return the segment por- 
tion of oi 


Example 


segment = FP__SEG (far—pointer); 


int foute (int character, 
FILE *stream); 


Function Outputs a single character to a file stream. 


Include File <stdio.h> 


character (in): Character to be written to the file 
stream | 
stream (in): File stream to be written to 
Example 


result = fpute (‘a’, fp); 


Note If successful, fputc returns the character written. If an error 
occurs, fpute returns EOF. 
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nt fouts (char *str, 
FILE *stream); 


Function Writes a character string to a file stream. 


str (in): Character string to be written to the data 
stream 
stream (in): File string to be written to 


Example 


last__char = fputs ("This is a test \n”, fp); 


Note If successful, fputs returns the last character written. If an 
error occurs, fputs returns EOF. 


int fread (void *pointer, 
nt num—bytes, int num—items, 
FILE *stream); 


Function Reads the specified number of bytes from a data stream. 


Include File <stdio.h> 


pointer (in): Pointer to the data buffer 

num_bytes (in): Number of bytes in each entry 

num —items (in): Number of items of num_—bytes length 
to read 
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Example 


num_—items_—_read = fread(buffer, 255, 5, fp); 


Note If successful, fread returns the number of items read. If an 
error occurs, fread returns an invalid count. 


void free (void *pointer); 
Function Releases a section of previously allocated memory. 


Include File <stdlib.h> 


pointer (in): Pointer to the previously allocated 
| memory 


Example 


free (list__node); 


unt freemem (unsigned segment); 


Function Frees a previously allocated DOS segment. 


Include File <dos.h> 


segment (in): Segment address of the memory block to 
release | 
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Example 
result = freemem (segment—addr); 


Note If successful, freemem returns 0. If an error occurs, it 
returns —l1. 


FILE *freopen (char *filename, 
char *access—type, 
FILE *stream); 


Function Substitutes a named file in place of a file stream. 


Include File <stdio.h> 


filename (in): Name of the file to open 

access__type (in): Specifies how the file is to be opened: 
r Read-only w Write 
a Append r+ Read/write 
w+ Create write a+ Append create 

if new file 

stream (in): File pointer to be associated with the 

file 
Example 


fp = freopen (“TEMP.DAT”, "w”, stdout); 


Note If successful, freopen returns the value of the file pointer. If 
an error occurs, it returns the value NULL. 


504 TURBO C PROGRAMMER’S LIBRARY 


double frexp (double value, 
ant *exponent); 


Function Splits a double-precision value into an exponent and 
mantissa. 


Include File <math.h> 


value (in): Value to be split 
exponent (out): Exponent of the value 
Example 


mantissa = frexp (value, &exponent); 
Note The value returned by frexp is the mantissa. 


int fscanf (FILE *stream, 
char format—sequence [, argument . . . ]}); 


Function Writes formatted output to a file stream. 


Include File <stdio.h> 


stream (in): File stream to write to 
format_sequence (in): Control sequence specifying the output 
format 
arguments (in): Data to be written to the file 
Example 


num_—_tfields = fscanf (fp, "%d %d %fn”", &a, &b, &c); 
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Note The fscanf routine returns the number of fields filled suc- 
cessfully. 


ant fseek (FILE *stream, 
long offset, nt location); 


Function Moves the file pointer in a file stream. 


Include File <stdio.h> 


stream (in): File stream desired 
offset (in): Desired byte offset in the file 
location (in): Location to offset from: 


SEEK—SET (0) Start of file 
SEEK—CUR (1) Current file position 
SEEK_—_END (2) End of file 


Example 


status = fseek (fp, 128, SEE K—SET); 


Note If successful, fseek returns the value 0. If an error occurs, it 
returns a nonzero value. 


int fsetpos (FILE *file —stream, 
const fpos—t *file—position); 


Function Sets the current file position for the specified file to the 
value last saved by fgetpos. 
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Include File <stdio.h> 


file_stream (in): File pointer associated with the de- 
sired file 
file__position (in): File position to be selected for the file 


Example 


result = fsetpos (fp, &file—position); 


# 


Note If successful, fsetpos returns 0; otherwise, it returns a non- 
zero value. 


ant fstat (char *handle, 
struct stat *stat—info); 


Function Returns information about the file associated with a file 
handle. 


Include File <stat.h> 


handle (in): File handle associated with the de- 
sired file 
stat_info (out): Structure containing the file 
information 
Example 


result = fstat (file—handle, &stat—info); 


Note If successful, fstat returns the value 0; otherwise, it returns 
the value —1. 
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long ftell (FILE *stream); 


Function Returns the current file-pointer location. 


Include File <stdio.h> 


stream (in): Data file stream desired 


Example 


loc = ftell (fp); 


unt fwrite (void *buffer, 
ant num—bytes, int num—items, 
FILE *stream); 


Function Writes the specified number of bytes to a data stream. 


Include File <stdio.h> 


pointer (in): Pointer to the data buffer 
num__bytes (in): Number of bytes in each entry 
num__items (in): Number of items of num_—_bytes 


length to read 


Example 


num_—items—written = fwrite(buffer, 255, 5, fp); 
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Note If successful, fwrite returns the number of items written. If 
an error occurs, it returns an invalid count. 


char *gcevt (double value, 
int num—digits, char *str); 


Function Converts a double-precision value into its character 
string representation. 


Include File <stdlib.h> 


value (in): | Double-precision value 
num_digits (in): Number of digits in the string 


str (out): | ASCII representation of the floating- 
| point value 


Example 


status = gevt (334.38, 10, str); 


Note gcvt returns a value of type string. 


void geninterrupt (int interrupt— 
number); 


Function Generates the desired software interrupt. 
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Include File <dos.h> 


interrupt_number (in): Desired software interrupt 
number 


Example 


geninterrupt (0x21); 


void far getarccoords 
(struct arccoordstype far *are 
—coord); 


Function Returns the coordinates of the last call to are. 


Include File <graphics.h> 


arc__coord (out): Structure containing the are coordinates 


Example 


getarccoords (&arc—coords); 


Note The structure type is 


struct arccoordstype { 
int x, y; 
int xstart, ystart, xend, yend; 


}; 
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void far getaspectratio (int far *x—aspect, 
ant far *y—aspect); 


Function Returns the aspect ratio for the current graphics mode. 


Include File <graphics.h> 


X—aspect (out): The aspect ratio for the current 
graphics mode 
y—aspect (out): The aspect ratio (normalized to 


10000) for the current mode 


Example 


getaspectratio (&x—aspect, &y—aspect); 


int far getbkcolor (void); 


Function Returns the current graphics mode background color. 
Include File <graphics.h> 


Example 


background—color = getbkcolor (); 


Note The setbkcolor routine sets the current background color. 
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int getc(FILE *stream); — 


Function Gets the next character in a file stream. 


Include File <stdio.h> 


stream (in): File stream to read a character from 


Note If getc encounters an end of file, it returns EOF. 


ant getebrk (void); 


Function Returns the current state of control-break checking, on 
(1) or off (0). 


Include File <dos.h> 


Example 
state = getcbrk(); 


Note The setcbrk routine enables or disables control-break 
checking. 


ant getch(void); 


Function Gets a character from the console device without echoing 
that character. | 
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Include File <conio.h> 


Example 


letter = getch(); 


Note If getch encounters an end of file or an error, it returns the 
value EOF. 


int getchar(void); 


Function Gets the next character from the stdin file stream. 
Include File <stdio.h> 


Example 


letter = getchar(); 


Note If getchar encounters an end of file or an error, it returns the 
value EOF. | | 


wnt getche(void); 


Function Gets a character from the console device echoing that 
character. 
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Include File <conio.h> 


Example 


letter = getche(); 


Note If getche encounters an end of file or an error, it returns the 
value EOF. The routine echoes the character to the current window. 


wnt far getcolor (void); 


Function Returns the current graphics color. 
Include File <graphics.h> 


Example 


foreground—color = getcolor (); 


Note The setcolor routine specifies the current color. 


wnt getcurdir (int drive, 
char *directory); 


Function Returns the current directory for the specified disk 
drive. 
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Include File <dir.h> 


drive (in): Disk drive ID desired (0 = current, 
1= A, 2= B) | 
directory (out): DOS pathname of the directory 
Example 


status = getcurdir (1, directory); 


Note If getcurdir encounters an error, the value —1 is returned. 


char *getewd (char *directory, 
ant num —bytes); 


Function Returns the current working directory. 


Include File <dir.h> 


directory (in): Buffer containing the current di- 
rectory 
num_—bytes (in): Number of bytes malloc should allo- 


cate to store the current directory. 
DOS directory names do not exceed 
64 characters 


Example 


status = getcwd (directory, 64); 


Note If getcwd encounters an error, it returns —1. 
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void getdate (struct date *current—date); 


Function Returns the current DOS system date. 


Include File <dos.h> 


current_date (out): Structure containing the current sys- 
tem date: 
struct date { 
int da__year; 
char da__day; 
char da__mon; 


} bf 


Example 


getdate (&current—date); 


void getdfree (int drive, 
struct dfree *disk—info); 


Function Returns the amount of free space on the specified 
drive. 


Include File <dos.h> 


drive (in): Disk drive desired (0 = A, 1 = B, 
2=C) 

disk__info (out): Structure containing the disk space in- 
formation: 


struct dfree { 
unsigned df_—avail; /* clusters available */ 


915 
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unsigned df__total; /* total clusters */ 
unsigned df__bsec; /* bytes per 
sector */ 


unsigned df_sclus; /* sectors per 
cluster */ 


Example 


status = getdfree (0, &disk—info); 


Note If getdfree encounters an error, it returns —1. 


ant getdisk (void); 


Function Returns the current disk drive. 
Include File <dir.h> 


Example 


drive = getdisk(); 


Note Disk drives are identified as 0 = A, 1 = B, 2=C. 


char *far getdta (void); 


Function Returns the address of the disk transfer. 


Include File <dos.h> 
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Example 


far__address = getdta(); 


Note By default, DOS places the disk transfer’s address at offset 
0x80 of the program segment prefix. 


char *getenu(char *environment — 
variable); 


Function Returns the value assigned to an environment variable. 


Include File <stdlib.h> 


environment_—variable (in): Environment variable to re- 
turn the value of 


Example 


str = getenv (“INCLUDE”); 


Note If getenv cannot find a matching entry, it returns a NULL 
string. 


void getfat (int drive, 
struct fatinfo *fat—info); 


Function Returns file allocation table information for the specified 
disk drive. | 
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Include File <dos.h> 


drive (in): Disk drive desired (0 = current, 1 = A, 2= 
B, 8 = C) 
fat_info (in): Structure containing the FAT information: 
| struct fatinfo { 
char fi__sclus; /* sectors/cluster / 
char fi__fatid; /* fat ID byte */ 
int fi__nclus; /* number of clusters */ 
int fi__bysec; /* bytes/sector */ 
j3 


Example 


getfat (1, &fat—info); 


void getfatd (struct fatinfo *fat—info); 


Function Returns file allocation table information for the default 
disk drive. 


Include File <dos.h> 


fat_info (in): Structure containing the FAT information: 
struct fatinfo { 
_ char fi_sclus; /*sectors/cluster */ 
char fi_fatid; /* fat ID byte */ 
int fi_nclus; /* number of clusters */ 
int fi__bysec; /* bytes/sector */ 
5 


Example 


getfatd (&fat—info); 
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void far getfillpattern (char far *fill— 
pattern); 


Function Copies a user-defined fill pattern into memory for fill 
operations in graphics mode. 


Include File <graphics.h> 


fill_pattern (in): An 8-byte array, where each byte 
represents 8 pixels; thus, an 8 X 8 
pattern can be specified 


Example 


get—fillpattern (my —pattern); 


void far getfillsettings (struct 
fillsettingstype far *fill—info); 


Function Returns the current graphics mode fill pattern and 
color. 


Include File <graphics.h> 


fill_info (out): Structure containing the current fill 
pattern and color: 
struct fillsettingstype { 
int pattern; 
int color; 


5 
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Example 


getfillsettings (&fill—info)); 


Note If the pattern returned is 12, a user-defined pattern is in 
effect. Predefined patterns include 


0 Empty fill 

1 Solid fill 

2 Line fill - 

3 Left-slash fill / 

4 Thick left-slash fill 
5 Backslash fill \ 

6 Thick backslash fill 
7 Light hatch fill 

8 Heavy crosshatch fill 
9 Interleaving line fill 
10 Wide-spaced dot fill 
11 Close-spaced dot fill 


wnt getftume (int file—handle, 
struct ftueme *file—stamp); 


Function Gets a file’s date and time stamp. 


Include File <dos.h> 


file_handle (in): File handle associated with the de- 
sired file 
file_stamp (out): Structure containing the file’s date 
| and time: 
struct ftime { 
unsigned ft__tsec:5; 
unsigned ft__min:6; 
unsigned ft__hour:5; 
unsigned ft_day: 5; 
unsigned ft__month:4; 
unsigned ft__year: 7; 
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Example 


status = getftime (filehandle, &file—stamp); 


Note If successful, getftime returns the value 0. 


wnt far getgraphmode (); 


Function Returns the current graphics mode. 
Include File <graphics.h> 


Example 


save__mode = getgraphmode (); 


Note See graphics.h for definitions of graphics modes. 


void far getimage (int left—corner, 
int top—corner, nt right —corner, 
ant bottom—corner, void far *image); 


Function Saves a bit image from the specified screen coordinates. 
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Include File <graphics.h> 


left__corner (in): Leftmost corner of the image 
to save 

top—corner (in): - Topmost corner of the image 
to save 

right—corner (in): Rightmost corner of the im- 
age to save 

bottom —corner (in): Bottommost corner of the im- 
age to save 

image (out): Buffer containing the bit 
image 

Example 


getimage (10, 20, 20, 30, buffer); 


Note The image size cannot exceed 64K. 


wnt far getmaxcolor (void); 


Function Returns the number associated with the last color value 
you can specify in graphics mode. 


Include File <graphics.h> 


Example 


max—color = getmaxcolor (); 
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wnt far getmaxx (void); 


Function Returns the maximum x screen coordinate. 
Include File <graphics.h> 


Example 


max__x = getmaxx (); 


unt far getmaxy (void); 


Function Returns the maximum y screen coordinate. 
Include File <graphics.h> 


Example 


max__y = getmaxy (); 


void far getmoderange (int graph—driver, 
ant far *lowest—mode, 
ant far *highest—mode); 


Function Returns the lowest and highest graphics mode values 
that you can specify for the given graph driver. 
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Include File <graphics.h> 


Example 


getmoderange (graph—driver, &low, &high); 


Note Ifthe graphics driver specified is invalid, both low and 
high are set to —1. 


void far getpalette (struct palettetype far *palette); 


Function Returns information about the current available colors. 


Include File <graphics.h> 


palette (out): Structure containing palette information: 
struct palettetype { 
unsigned char size; 
signed char colors [MAX--COLORS +1} 


iF 


Example 


getpalette (palette); 


Note See graphics.h for color definitions. 
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char *getpass (char *prompt); 


Function Prompts the user to enter a password and returns the 
password entered. 


Include File <conio.h> 


prompt (in): Character string prompt 


Example 


pass = getpass ("Enter your secret password”); 


Note The password can contain up to eight characters. 


wnt far getprixel (int x—loc, 
ant y—loc); 


Function Returns the color of the pixel at the specified x,y 
location. 


Include File <graphics.h> 


x_—loc, y__loce (in): The x and y location of the 
desired pixel 


Example 


color = getpixel (10, 20); 
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unsigned getpsp (void); 


Function Returns the program segment prefix address. 
Include File <dos.h> 


Example 


segment_addr = getpsp (); 


Note getpsp only works under DOS 3.x. 


char *gets (char *string) 


Function Returns a character string from the stdin stream. 


Include File <stdio.h> 


string (out): Character string read 


Example 


status = gets (str); 


Note If gets encounters an error or end of file, it returns EOF. It 
replaces a newline character with the NULL character. 
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nt gettext (int left—corner, 
nt top—corner, 
wnt right—corner, int bottom—corner, void *buffer); 


Function Copies text from your screen display into a buffer. 


left__corner (in): Specifies the x coordinate of the 
upper-left corner of the region to 
copy 

top—corner (in): Specifies the y coordinate of the 
upper-left corner of the region to 
copy 


bottom_—corner (in): Specifies the y coordinate of the 
lower-right corner of the region to 


copy 
right_corner (in): Specifies the x coordinate of the 
lower-right corner of the region to 


Copy 
buffer (out): Buffer in memory that the text is 


copied to 


Example 

gettext (0, 10, 20, 79, buffer); 

Note All coordinates are screen coordinates, as opposed to window 
coordinates. Calculate your buffer size as 


size = (rows) * (columns) * 2 
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gettextinfo (struct text —info “teat — 
record); 


Function Returns specifics about text mode. 


Include File <conio.h> 


text__record (out): Structure containing text mode infor- 

mation: 

struct text_info { 
unsigned char winleft; 
unsigned char wintop; 
unsigned char winright; 
unsigned char winbottom; 
unsigned char attribute; 
unsigned char normattr; 
unsigned char currmode; 
unsigned char screenheight; 
unsigned char screenwidth; 
unsigned char curx; 
unsigned char cury; 


Example 


gettextinfo (&text—record); _ 


void far gettextsettings 
(struct textsettingstype far text — 
record); 


Function Returns information about graphics mode text settings. 


Include File <graphics.h> 


text__record (out): 


Example 
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Structure containing graphics text 
information: 
struct textsettingstype { 

int font; 

int direction; 

int charsize; 

int horiz; 

int vert; 


gettextsettings (&text_record); 


void gettime (struct time *system—time); 


Function Returns the current system time. 


Include File <dos.h> 


system_—_time (out): 


Example 


gettime (&current—time); 


Structure assigned the current sys- 
tem time: 

struct time { 

unsigned char ti__min; 

unsigned char ti__hour; 

unsigned char ti__hund; 

unsigned char ti__sec; 


i 
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enshansil anterrupt 
(*getvect(int interrupt—number))( ); 


Function Returns the interrupt vector address for the specified in- 
terrupt. 


Include File <dos.h> 


interrupt__ number (in): Interrupt number to return the 
vector for : 


Example 


vector_—address = getvect (5); 


_ getviewsettings | 
(struct viewporttype far *view—port); 


Function Returns specifics about the current viewport. 


Include File <graphics.h> 


viewport (out): Structure containing specifics about the 
current viewport: 
struct viewporttype { 
int left, top, right, bottom; 
int clipflag; 
S3 
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Example 


getviewsettings (&view—_port); 


ut getverify (void); 


Function Returns the current state of disk verification. 
Include File <dos.h> 


Example 


status = getverify (); 


Note If disk verification is on, getverify returns the value 1. If disk 
verification is off, getverify returns 0. 


int getw (FILE *stream); 


Function Gets an integer value from a data stream. 


Include File <stdio.h> 


stream (in): Data file stream 


Example 


value = getw (fp); 
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int far getx (void); 


Function Returns the current position’s x coordinate in graphics 
mode. | | 


Include File <graphics.h> 


Example 


xloc = getx(); | 


Note Coordinates are viewport relative. 


wnt far gety (void); 


Function Returns the current position’s y coordinate in graphics 
mode. 


Include File <graphics.h> 


Example 


yloc = gety(); 


Note Coordinates are viewport relative. 
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struct tm *gmtime(long *clock); 


Function Converts a date and time to Greenwich mean time. 


Include File <time.h> 


clock (in): Structure containing the time to convert 


Example 


gmt—time = gmtime (&current—time); 


void gotoxy (int x—loe, int y 
—loc); 


Function Sets the cursor position (column,row) in text mode. 


include File <conio.h> 


x__loe (in): Desired column for the cursor 
y—loe (in): Desired row for the cursor 
Example 


gotoxy (10, 10); 


Note The cursor is positioned within the current window. 
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char far *grapherrormsg (int error— 
code); 


Function Returns an error message string for the specified graph- 
result. 


Include File <graphics.h> 


error—code (in): Error code value contained in graph- 
~ result | 


Example 


msg = grapherrormsg (—8); 


void far —graphfreemem (void far *pointer, 
unsigned bytes); 


Function Releases memory allocated for graphics by —graph- 
getmem. 7 


Include File <graphics.h> 


pointer (in): | Pointer to the allocated memory 
bytes (in): Number of bytes to release 
Example 


_graphfreemem (buffer, 1024); 
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void far *far 
—graphgetmem (unsigned size); 


Function Allocates memory for graphics manipulation. 


Include File <graphics.h> 


size (in): Number of bytes of memory to allocate 


Example 


buffer = —graphgetmem (1024); 


unt far graphresult (void); 


Function Returns the error code for the last unsuccessful graphics 
operation. 


Include File <graphics.h> 


Example 

status = graphresult (); 

Note Once you invoke graphresult, Turbo C resets its value to 0. 
Common error status codes include 


0 No error 
=], Graphics not installed; use initgraph 
7 Graphics hardware not found 
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==5 Device driver not found 

zac Invalid device driver file 

—5 Insufficient memory to load driver 
—6 Out of memory in sean fill 


at | Out of memory in flood fill 

—8 Font file not found 

—9 Insufficient memory to load font 

—10 Invalid graphics mode for driver selected 
—l1 Graphics error | 

=12 Graphics I/O error 

={3 Invalid font file 

—14 Invalid font number 

“15 Invalid device number 


wnt gsignal (int signal); 


Function Raises the specified signal, and executes the action 
routine. 


Include File <signal.h> 


signal (in): Software signal, ranging from 1 to 15 


Example 


result = gsignal (2); 


Note The gsignal routine returns the value returned by the action 
defined or the constant SIG__DFL if the signal is invalid. 
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void harderr (int (*function—ptr) ()); 


Function Defines a hardware error handler. 


Include File <dos.h> 


function__ptr (in): Address of the function to serve as the 
hard error handler 


Example 


harderr (my—handler); 


Note Hard errors occur when interrupt 0x24 is invoked. The most 
common occurrence of this is an open disk drive. You can define your 
own error-handling routine. When interrupt 0x24 occurs, your rou- 
tine will receive these parameters: 


(int error—value, int ax, int bp, int si); 


See the Turbo C manual for more specifics on the information con- 
tained in these parameters. 


void hardresume (int resume—code); 


Function Returns 2 (abort), 1 (retry), or 0 (ignore) based upon a 
hard error-handling routine to DOS. 
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Include File Seah 


resume_code (in): Return status value (2=abort, 
1=retry, 0=ignore) - 


Example | 


hardresume (0); 


void hardretn (int error—code); 


Function Returns an error status code to the application based 
upon a hard error handler. 


Include File <dos.h> 


error—code (in): Value returned to the application 
program 


Example 


hardretn (0); 


void highvideo (void); | 
Function Selects high-intensity attributes for text display. 


Include File <conio.h> 
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Example 
highvideo (); 


Note This routine allows you to make some text appear in a heav- 
ler boldface on your screen display. 


double hypot (double x, double y); 


Function Returns the hypotenuse of a right triangle. 


Include File <math.h> 


X (in): x side of the triangle 
y (in): y side of the triangle 


Example 


z = hypot (x, y); 


unsigned far imagesize (int left—corner, 
int top—corner, 

ant right—corner, 

ant bottom—corner); 


Function Returns the number of bytes required to store the speci- 
fied graphics image. 
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Include File <graphics.h> 


left__corner (in): 


top_—corner (in): 


Specifies the x coordinate of the 
upper-left corner of the region to 

ae , | 
Specifies the y coordinate of the 


- upper-left corner of the region to 


bottom—corner (in): 


right—corner (in): 


Example 


Copy 
Specifies the y coordinate of the 
lower-right corner of the region to 


copy. 


Specifies the x coordinate of the 


lower-right corner of the region to 
copy 


num_—_bytes = imagesize (10, 10, 20, 20); 


void far initgraph (int far *graph—driver, 


wnt far *graph—mode, 


char far *driver—path); 


Function Initializes graphics by loading a graphics driver from 
and placing the system into graphics 


disk, validating the driver, 
mode. | 


Include File <graphics.h> 


graph_—driver (in): 
graph_mode (in): 
driver__path (in): 


Graphics driver for system 
Desired graphics mode 

DOS subdirectory that con- 
tains graphics device driver 
files 
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Example 


initgraph (&graphics—driver, &graphics—mode, ””); 


Note If driver—path is NULL, BGI files must be in the current 
directory. Use the following values for graphics drivers: 


DETECT Autodetect correct driver for hardware 
CGA monitor 

MCGA monitor 

EGA monitor 

EGA64 monitor 

EGAMONO monitor 
RESERVED 

HERCMONO Hercules monitor 
ATT400 monitor 

VGA monitor 

PC3270 monitor 


—- OoOontnor wher © 


—) 


See the file graphics.h for graphics modes. 


unt nport (int port—number); 


Function Inputs a word from the specified hardware port. 


Include File <dos.h> 


port_number (in): Desired hardware port number 


Example 


status = inport (0x3da); 
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ant anportb (int port—number); 


Function Inputs a byte from the specified hardware port. 


Include File <dos.h> 


port__number (in): Desired hardware port number | 


Example 


status = inportb (0x3da); 


void unsline (void); 


Function Inserts a blank line at the current cursor position in 
the current text window. 


Include File <conio.h> 


Example 


insline( ); 


Note All lines (including the current line and below) are moved 
down one line. 
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unt nt86x (int interrupt —number, 
union REGS *inregs, 
union REGS *outregs); 


Function Invoke the specified 8086 interrupt and assign the 8086 
registers the values contained in the structure inregs. 


Include File <dos.h> 


interrupt—number (in): Desired 8086 interrupt 


inregs (in): Structure containing the values to 
assign to the 8086 registers (see 
Chapter 6) 

outregs (out): Structure containing the values 


contained in the 8086 registers fol- 
lowing the interrupt service 


Example 


status = int86 (0x10, inregs, outregs)); 


Note int&86 returns the value of the AX register upon completion of 
the interrupt routine. 
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ant wmt86 (int interrupt—number, 
union REGS *inregs, 

union REGS *outregs, 

struct SREGS *segregs); 


Function Invokes the specified 8086 interrupt and assigns the 
8086 registers the values contained in the structures inregs and 
sregs. 


Include File <dos.h> 


interrupt—_number (in): Desired 8086 interrupt 

inregs (in): Structure containing the values 
to assign to the 8086 registers 
(see Chapter 6) 

outregs (out): Structure containing the values 
contained in the 8086 registers 
following the interrupt service 

sregs (in/out): | Structure containing the 8086 
segment registers 


Example 


status = int&86x (0x10, inregs, outregs, sreg's); 


Note int&86x returns the value of the AX register upon completion 
of the interrupt service routine. 
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wnt intdos(union REGS *inregs, 
union REGS *outregs); 
Function Invokes DOS interrupt 0x21 (general-purpose interrupt) 


after assigning the 8086 registers the values contained in the struc- 
ture inregs. 


Include File <dos.h> 


inregs (in): Structure containing the values to assign 
to the 8086 registers (see Chapter 6) 

outregs (out): Structure containing the values contained 
in the 8086 registers following the inter- 
rupt service 


Example 


status = intdos (inreg's, outregs); 


Note intdos returns the value of the AX register upon completion 
of the interrupt service routine. 


wnt intdosx(union REGS *inregs, 

union REGS *outregs, 

struct SREGS sregs); 

Function Invokes DOS interrupt 0x21 (general-purpose inter- 


rupt) after assigning the 8086 registers the values contained in ee 
structures inregs and sregs. 
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Include File <dos.h> 


inregs (in): Structure containing the values to 
assign to the 8086 registers (see 
Chapter 6) | 

outregs (out): Structure containing the values 


contained in the 8086 registers fol- 
lowing the interrupt service 

sregs (in/out): Structure containing the 8086 seg- 
ment registers 


Example 


status = intdosx (inregs, outregs, sregs); 


Note intdosx returns the value of the AX register upon completion 
of the interrupt service routine. 


void intr (int interrupt— 
number, 
struct REGPACK *regs); 


Function Execute 8086 interrupt service routine. 


Include File <dos.h> 


interrupt_number (in): Desired interrupt service routine 
regs (in/out): Structure containing 8086 registers: 
struct REGPACK { 
unsigned r__ax, r__bx, r__ex, r—dx; 
unsigned r__bp, r__si, r—di, r—ds; 
unsigned r__es, r__flagss; 
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Example 


intr (5, regs); 


wt roctl int devhandle, 
nt command [int argdx, 
mt argex)); — 


Function Extended control to an I/O device. 


Include File <ijo.h> 


devhandle (in): Handle to the desired device 
command (in): Specific command to perform: 
0 Get device info 
1 Set device info into argdx 
2 Read the number of bytes specified by 
argex into the buffer pointed to by 
argdx 
3 Write the number of bytes specified by 
argcex from the buffer pointed to by 
argdx 
4 Same as command 2. Treat the device 
handle as a disk-drive specifier. 
5 Same as command 3. Treat the device 
handle as a disk-drive specifier. 
Get input status 
Get output status 
Test device removeability 
Reset sharing conflict retry count 


mm CON SD 


pad 


Example 


status = ioctl (handle, 0, &argex, &argdx); 


Note This routine provides direct device-driver access. 
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so) 


int isalnum(int character); 


Function Returns 1 if the character contained in the parameter 
character is alphanumeric; otherwise, returns 0. 


Include File <io.h> 


character (in): Character to examine 


Example 


while (isalnum (letter)); 


int isalpha (int character); — 


Function Returns 1 if the character contained in the parameter 
character is in the range A-Z or a-z; otherwise, returns 0. 


Include File <ijo.h> 


character (in): Character to examine 


Example 


while (isalpha (letter)); 
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ant _sascii(int character); 


Function Returns 1 if the character contained in the parameter 
character is in the range 0-127. 


Include File <jo.h> 


character (in): Character to examine 


Example 


while (isascii (letter)); 


wt rsatty (int devicehandle); 


Function Returns 1 if the device associated with the device handle 
is a tty device. 


Include File <io.h> 


devicehandle (in): Handle to the desired device 


Example 


status = isatty (handle); 


Note isatty returns the value 1 if the device is a console, terminal, 
printer, or serial port. 
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ant isentrl(int character); 


Function Returns 1 if the character contained in the parameter 
| character is in the range 0-0x1F. 


Include File <io.h> 


character (in): Character to examine 


Example 


while (isentr] (letter)); 


wnt sdigit(iint character); 


Function Returns 1 if the character contained in the parameter 
character is in the range ’0’-’9’. | 


Include File <io.h> 


character (in): Character to examine 


Example 


while (isdigit (letter)); 
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ant isgraph(int character); 


Function Returns 1 if the character contained in the parameter 
character is a printable character other than a space. 


Include File <io.h> 


character (in): Character to examine 


Example 


while (isgraph(letter)); 


ant slower(int character); 


Function Returns 1 if the character contained in the parameter 
character is a lowercase character. 7 


Include File <io.h> 


character (in): Character to examine 


Example 


while (islower(letter)); 
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int isprint(int character); 


Function Returns 1 if the character contained in the parameter 
character is a printable character. 


Include File <jo.h> 


character (in): Character to examine 


Example 


while (isprint(letter)); 


unt ispunct(int character); 


Function Returns 1 if the character contained in the parameter 
character is a punctuation character (isentrl or isspace). 


Include File <io.h> 


character (in): Character to examine 


Example 


while (ispunct(letter)); 
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mnt isspace(int character); 


Function Returns 1 if the character contained in the parameter 
character is a space, carriage return, tab, form feed, newline, or 
vertical tab. 


Include File <io.h> 


character (in): Character to examine 


Example 


while (isspace(letter)); 


ant isupper(int character); 


Function Returns 1 if the character contained in the parameter 
character is an uppercase letter. 


Include File <io.h> 


character (in): Character to examine 


Example 


while (isupper(letter)); 


wnt sxdigit(int character); 


Function Returns 1 if the character contained in the parameter 
character is a hexidecimal digit (0-9, ’A’-’F’). 
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Include File <a0.h> 


character (in): Character to examine 
Example 


while (isxdigit(letter)); 


char *itoa (int value, 
char *str, int radix); 


Function Converts an integer value to its ASCII representation. 


Include File <stdlib.h> 


value (in): Integer value to convert 
str (out): String to contain ASCII representation 
radix (in): Specifies the desired radix (2-36): 


2 (binary), 10 (decimal), 8 (octal), 16 (hex), 
and so forth) 


Example 


result = itoa (3344, str, 10); 


Note toa does not return an error status. 


wt kbhit (void); 


Function Returns a nonzero value if keys are available in the key- 
board buffer. If no keys have been pressed, kbhit returns the value 0. 
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Include File <conio.h> 


Example 


while (! kbhit()); 


void keep (int status, 
wt paragraphs); 
Function Terminates the current program resident in memory. 


Include File <dos.h> 


status (in): Exit status value returned to DOS 

paragraphs (in): Number of 16-byte paragraphs DOS 
must allocate for the memory-resident 
program 


Example 


keep (1, 1000); 


Note For more information on memory-resident C programs, refer 
to Osborne/McGraw-Hill’s C Power User’s Guide. 


long labs (long value); 
Function Returns the absolute value of a long variable. 
Include File <math.h> 


value (in): Value of which to return the absolute 
value 
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Example 


result = labs (—3448223L); 


double ldexp (double value, 
ant exponent); 


Function Returns the result of value * 2 raised to the exponent. 


Include File <math.h> 


value (in): | Value to be multiplied by the expression 
2 to the power of exponent 
exponent (in): Power to which to raise the value 2 
Example 


result = ldexp (value, 10); 


ldiv—t ldw (long numerator, 
long denominator); 


Function Returns the quotient and remainder of the integer divi- 
sion of two numbers. | 


Include File <stdlib.h> 


numerator (in): Number to be divided 
denominator (in): Number divided into the numerator 
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Example 


result = Idiv (160000L, 56555L); 


Note ldiv_t is a structure containing: 


typedef struct { 
long quot; 
long rem; 

} ldiv_t; 


void *lfind (void *key—desired, 
void *base—address, 

ant *num—elements, 

ant element—width, 

ant (*compare—function)()); 


Function Performs a generic search of an array for the specified 
key value. 


Include File <stdlib.h> 


key—desired (in): Pointer to the desired value 

base__address (in): Starting address of the array to 
search 

num__elements (in): Number of elements in the array 

element—width (in): Number of bytes in each element 


compare——function (in): Pointer to the function to be used 
for element comparisons: 
Return a value < 0 ifa<b 
Return a value = 0ifa=b 
Return a value > 0 ifa>b 
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Example 


location = lfind (name, namearray, &num—elements, 
sizeof(name), str__comp); 


Note This is a generic sequential search routine. It will work for 
all types (int, float, char, and so forth). lfind returns the address of 
the matching element if it is found, or the value 0, otherwise. 


void far line (ant xstart, 
unt ystart, int xend, int yend); 


Function Draws a line between two specified points. 


Include File <graphics.h> 


xstart, ystart (in): x and y start coordinates of the line 
xend, yend (in): x and y end coordinates of the line 
Example 


line (10, 10, 20, 20); 


Note line uses the current drawing color. 


void far linerel (int x«—offset, 

wnt y—offset),; 
Function Draws a line from the current position to the position 
specified by the x and y offset. 
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Include File <graphics.h> 


x __offset (in): Relative distance along x axis 
y—offset (in): Relative distance along y axis 
Example 


linerel (10, 10); 


Note linerel uses the current drawing color. 


void far lineto (ant x—loc, 
wnt y—loc); 


Function Draws a line from the current position to the position 
xloc, yloc. 


Include File <graphics.h> 


x__loe (in): Point on x axis to which to draw 
y—loe (in): Point on y axis to which to draw 
Example 


lineto (10, 10); 


Note lineto uses the current drawing color. 
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struct tm *localtime (long *seconds); 


Function Returns a structure containing the current time 
broken down into its individual parts. 


Include File <time.h> 


seconds (in): © Seconds since 00:00:0 GMT 01/01/1970 


Example 


current—time = localtime (&timeinseconds); 


Note The structure returned contains: 


struct tm { 

int tm__sec; 
int tm__min; 
int tm__hour; 
int tm__mday; 
int tm__mon; 
int tm__year; 
int tm__wday; 
int tm__yday; 
int tm__isdst; 
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wt lock (int filehandle, 
long offset, long length); 


Function Locks a portion of a file as specified. 


Include File <io.h> 


filehandle (in): File handle associated with the de- 
sired file 
offset (in): Offset to the first byte to lock 
length (in): Number of bytes to lock 
Example 


status = lock (file, 256, 512); 


Note lock provides file locking under DOS 3.X. If successful, lock 
returns the value 0; otherwise, it returns —1. 


double log (double value); 


Function Returns the natural logarithm for the specified value. 


Include File <math.h> 


value (in): Value of which to return the natural 
logarithm 
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Example 


result = log (value); 


double log10 (double value); 


Function Returns the log to the base 10 of the specified value. 


Include File | <math.h> 


value (in): Value of which to return the log to the base 10 


Example 


result = log10 (value); 


void longymp Gmp—buf task—state, 
nt return—value); 


Function Performs a long goto outside of the current block of code. 


Include File <setjmp.h> 


task__state (in): Buffer storing the values of CS, 
DS, ES, SS, SI, DI, SP, FP, and 
flags 
return—value (in): Value to return from jump 
Example 


longjmp (task__state, 1); 
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void lowvideo (void); 


Function Selects low-intensity attributes for text display. 
Include File <conio.h> 


Example 


lowvideo (); 


Note This routine allows you to make some text appear duller on 
your screen display. 


unsigned long—lrotl (unsigned long long—value, 
ant num—shifts); 


Function Rotates an unsigned long value to the left by the speci- 
fied number of shifts. 


Include File <stdlib.h> 


long—value (in): Unsigned long value to shift left 
num_shifts (in): Number of shifts to perform 
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Example 


long—result = —lrotl (address, 16); 


unsigned long 
—lrotr (unsigned long long—value, 
ant num—shifts); 


Function Rotates an unsigned long value to the right the specified 
number of shifts. 


Include File <stdlib.h> 


long_value (in): Unsigned long value to shift right 
num_shifts (in): Number of shifts to perform 
Example 


long__result = —lrotr (address, 16); 


void *lsearch (void tah cae 
void *base—address, 
ant num—elements, 
ant width, 
ant (*compare—function)()); 
Function Searches an array for a specific value. If the value is 


found, lsearch returns its address. Otherwise, lsearch appends it to 
the end of the list. 
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Include File <stdlib.h> 


desired__key (in): Value to search for, or append if 
not found 

base__address (in): Starting address of the array 

num_—elements (in): Number of elements in the 
array 

width (in): Number of bytes in each 
element 


compare—function (in): Pointer to the function to be 
used for the element compar- 
ison: 
Return a value < 0 ifa<b 
Return a value = 0ifa=b 
Return a value > 0ifa>b 


Example 


result = lsearch (&ssan, table, &num-_—elements, sizeof (ssan), 
compare—float); 


Note If lsearch appends the value, it returns the value 0. Other- 
wise, lsearch returns the address of the desired element. 


long lseek (int filehandle, 
long offset, int location); 


Function Moves the file pointer associated with the given file han- 
dle to the specified offset. 


Include File <io.h> 


filehandle (in): File handle associated with the desired 
file 
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offset (in): Desired offset within the file 

location (in): Location from which to branch: | 
SEEK__SET (0) Beginning of file 
SEEK—CUR (1) Current position 
SEEK END (2) End of file 


Example 


result = lseek (filehandle, 1024, SEEK_SET); 


Note If successful, lseek returns the new file position; otherwise, it 
returns the value —1. 


char *ltoa (long value, 
char *str, int radix); 


Function Converts a long int value to its ASCII representation. 


Include File <stdlib.h>. 


value (in): Long value to convert 
str (out): String to contain ASCII representation 
radix (in): Specifies the desired radix (2-36): 


2 (binary), 10 (decimal), 8 (octal), 16 (hex), 
and so forth 


Example 


result = ltoa (834114L, str, 10); 
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Note ltoa does not return an error status. 


void *malloc (size 
—t num—bytes); 


Function Allocates the number of bytes specified from memory. 
Include File <alloc.h> 
num__bytes (in): Number of bytes to allocate 


Example 


node = malloc (255); 


Note If successful, malloc returns a pointer to the allocated 
memory. If unsuccessful, malloc returns the value NULL. 


double matherr (struct exception *except); 


Function Defines a math error exception handler. 
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Include File <math.h> 


except (in): Structure containing information about the 
math exception: 
struct exception { 
int type; 
char *name; 
double arg1, arg2, retval; 


i; 


Example 


matherr is not directly called by the user 


Notes When Turbo C encounters an exception while performing a 
mathematical routine from the run-time library, it invokes the rou- 
tine matherr. By default, this routine simply returns 0. However, you 
can develop your own matherr routine to interrogate the exception 
structure. The file math.h defines each of the possible exceptions. 


void mememp (void *ptr1, void *ptr2, 
unsigned num—bytes); 


Function Compares the values pointed to by ptr1 to those pointed 
to by ptr2. 
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Include File <mem.h> 


ptr1 (in): ~ Pointer to the first block of memory 
ptr2 (in): Pointer to the second block of memory 
num__bytes (in): Number of bytes to compare 


Example 


result = mememp (sl, s2, 255); 


Note memecmp returns one of the following: 


0 if sl == s2 
> O0if sl > s2 
<0Oif sl <s2 


void *memcpy (void *destination, 
void *source, 
unsigned num—bytes); 


Function Copies the number of specified bytes from one memory 
location to another. 


Include File <mem.h> 


destination (in): Location to which the bytes are 
copied 
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source (in): | Location from which the bytes 
are copied 
num_bytes (in): Number of bytes to copy 
Example 


memepy (array—b, array—a, sizeof (array —a)); 


void *memcepy (void *destination, 
void *source, 
unsigned char letter, 
unsigned num—bytes); 
Function Copies the number of specified bytes from one memory 


location to another, or until the letter contained in the variable letter 
is copied to the destination. 


Include File <mem.h> 


destination (in): Location to which the bytes are 
| copied 

source (in): Location from which the bytes 
are copied 

letter (in): Letter that, when copied, termin- 
ates the copy 

num__bytes (in): Number of bytes to copy 

Example 


memceepy (array—b, array—a, ‘a’, sizeof (array—a)); 
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Note memccpy returns the byte immediately following letter if let- 
ter was copied. Otherwise, memecpy returns the value NULL. 


void *memchr (void *ptr, 
char letter, unsigned num—bytes); 


Function Searches the first num_—bytes of an array for the letter 
contained in the variable letter. 


Include File <mem.h> 


ptr (in): Pointer to the array in memory 
letter (in): Letter for which to search 
num _bytes (in): Number of bytes to search in the array 


Example 


location = memchr (str, ‘A’, sizeof (str)); 


Note memchr returns a pointer to the first occurrence of letter in 
the string, or the value NULL if letter is not found. 
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— *void memicmp (void *ptr1, void *ptr2, 
unsigned num—bytes); 


Function Compares the values pointed to by ptr1 to those pointed 
to by ptr2 and ignores the case of each letter. 


Include File <mem.h> 


ptr1 (in): Pointer to the first block of memory 
ptr2 (in): Pointer to the second block of memory 
num__bytes (in): Number of bytes to compare 


Example 


result = memicmp (sl, s2, 255); 


Note memicmp returns one of the following: 


Oifsl == s2 
> 0 if sl > s2 
<0ifsl <s2 


void *memmove (void *destination, 
void *source, 
unsigned num—bytes); 


Function Copies num_—bytes from the source memory location to 
the destination. 
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Include File <string.h> 


destination (in): Pointer to the destination location in 
memory 
source (in): Pointer to the source location in mem- 


ory that contains the data to copy 
num__bytes (in): Number of bytes to copy 


Example 


ptr = memmove (str1, str2, strlen (str1)); 


void *memset (void *ptr, 
char letter, unsigned num—bytes); 


Function Sets the number of bytes specified in the array pointed 
to by ptr to the value in the variable letter. 


Include File <mem.h> 


ptr (in): Pointer to the array in memory 
letter (in): Letter to assign to the memory locations 
num__bytes (in): Number of bytes to which to assign the 
value 
Example 


memset (str, ‘A’, sizeof (str)); 


Note memset returns a pointer to the array in memory. 
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ant mkdir (char *DOSpathname); 
Function Creates the specified DOS subdirectory. 


Include File <dir.h> 


DOSpathname (in): DOS subdirectory name to create 


Example 


status = mkdir ("TESTDIR”); 


Note If successful, mkdir returns the value 0. Otherwise, mkdir 
returns the value —1. | 


void far *MK—FP (unsigned segment, 
unsigned offset); 


Function Returns a far somter that is a combination of the pro- — 
vided segment and offset. 


Include File <dos.h> 


segment (in): Segment address portion of the far address 
offset (in): Offset address portion of the far address 


Example 


far_address = MK__FP (segment, offset); 
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char *mktemp (char *template); 


Function Creates a unique filename. 


Include File <dir.h> 


template (in): A string containing 6 X’s (XXXXXX) 


Example 
result = mktemp (template); 
Notes The string template should be in the form "XXXXXX”". The 


routine mktemp replaces the ”X’s” with a unique filename in the 
form AA.AAA. mktemp returns a pointer to the new filename. 


double modf (double value, 
double *integer—portion); 


Function Splits a double-precision value into an integer and frac- 
tional portion. 


Include File <math.h> 


value (in): Value to split 
integer__portion (out): Integer portion of the value 


Example 


fractional__part = modf (value, &integer—part); 
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void movedata (int source— 
segment, int source—offset, 
unt target—segment, 

nt target—offset, 

unsigned num—bytes); 


Function Moves the number of specified bytes from the source 
location to the target. 


Include File <mem.h> 


source__segment (in): Segment address of the source 
location 

source—offset (in): | Offset address of the source 
location 

target_segment (in): Segment address of target location 

target_offset (in): Offset address of the target location 

num_bytes (in): Number of bytes to transfer 


Example 


movedata (segment, offset, 0xB000, 0, 4000); 


Note movedata does not return a value. 


void far moverel (int x«— 
offset, int y—offset); 


Function Moves the current position to the position specified by the x 
and y offsets. 


Include File <graphics.h> 


x__offset (in): 
y—offset (in): 


Example 


moverel (10, 10); 
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Relative distance along x axis 
Relative distance along y axis 


ant movetext (int left—corner, 


ant top—corner, 

wnt right—corner, 
ant bottom—corner, 
ant new—leftcorner, 
int new—topceorner); 


O77 


Function Moves a region of text from one location on the screen 


to another. 


left—corner (in): 
top—corner (in): 
bottom _—corner (in): 


right__corner (in): 


- new__leftcorner (in): 


new__topcorner (in): 


Specifies the x coordinate of 
the upper-left corner of the 
region to move 

Specifies the y coordinate of 
the upper-left corner of the 
region to move 

Specifies the y coordinate of 
the lower-right corner of the 
region to move 

Specifies the x coordinate of 
the lower-right corner of the 
region to move 

Location to which to move 
text 

Location to which to move 
text 
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movetext (15, 20, 21, 25, 5, 10); 


Note If successful, movetext returns the value 1; otherwise, move- 
text returns 0. 


void far moveto (int x—loe, 
ant y—loc); 


Function Moves the current position to the position xloc, yloc. 


Include File <graphics.h> 


x—loe (in): Point on x axis to which to move 
y—loc (in): Point on y axis to which to move 
Example 


moveto (10, 10); 


void movmem (void *source, void target, 
unsigned num—bytes); 


Function Moves the number of bytes specified from a source to a 
target location. | 


Include File <mem.h> 


source (in): Pointer to the source location in mem- 
ory 
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target (in): Pointer to the target location in mem- 
ory 
num__bytes (in): Number of bytes to move 
Example 


movmem (my—array, your—array, sizeof(my—array)); 


Note movmem does not return a value. 


void normvideo (void); 


Function Selects normal video display attributes for text following 
a call to either highvideo or lowvideo. 


Include File <conio.h> 


Example 


normvideo (); 


void nosound (void); 
Function Turns off the IBM PC speaker. 


Include File <dos.h> 


Example 


nosound(); 
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int —open (char *DOSpathname, 
int access—type); 


Function Opens a file for read or write access. 


Include File <io.h> 


DOSpathname (in): String containing the filename to 


open 
access__type (in): Specifies the mode of access to 
support: 
O_NOINHERIT Not passed to child 
process 
O__DEN YALL Only current handle 
can access 


O_DENYWRITE Only current handle ~ 
can write access 
any open can read 
the file 

O_DENYREAD Only current handle 
can read access any 
other open can 
write 

O_—DENYNONE = Shared file 


Example 


handle = —open ("“TEST.DAT”, O__DENYNONE); 


Note This function is unique to DOS. If an error occurs, —open | 
returns the value —1. | 
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unt open (char *DOSpathname, 
int access—typef, int permissions }); 


Function Opens a file for read or write access. 


Include File <io.h> 


DOSpathname (in): String containing the filename to 
open 

access__type (in): Specifies the mode of access to 
support: 


O_-RDONLY Read-only access 
O_WRONLY Write-only access 
O_RDWR Read/write access 
O_NDELAY Not used 
O_APPEND Open in append 


mode 
O_CREAT Create the file if non- 
existent 
O__TRUNC Truncate the file 
to 0 bytes if it exists 
O_EXCL Not used 
O_BINARY Binary mode open 
O_TEXT Text mode open 
permission (in): Defines the file permissions: 
S_IWRITE Write access granted 
S_IREAD Read access granted 
S—IREAD | Read/write access 


S—IWRITE 


Example 


handle = open (“TEST.DAT”, O_BINARY); 
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void outport (int pord—id, 
ant word); 


Function Outputs a value to the specified hardware port. 


Include File <dos.h> 


port__id (in): Desired port address 
word (in): Value to output to the port 
Example 


outport (Ox3da, 0); 


void outportb (int pord—id, 
char byte); 


Function Outputs a byte value to the specified hardware port. 


Include File <dos.h> 


port—id (in): Port address desired 
byte (in): Value to output to the port 
Example 


outportb (Ox3da, 255); 
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void far outtext (char far *string); 


Function Outputs a character string at the current position in the 
viewport. 


Include File <graphics.h> 


string (in): Character string to display 


Example 


outtext (“TEXT”); 


void far outtextxy (int x—loe, 
wnt y—loc, char far *string); 


Function Displays a text string within the current viewport at the 
specified x and y location. 


Include File <graphics.h> 


x—loe, y—_loe (in): Location in the viewport at 
which to display the string 
string (in): Character string to display 
Example 


outtextxy (5, 10, "TEXT”); 
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char *parsfnm (char *command—line, 
struct feb *filecontrol—block, 
ant al—register); 


Function Parses a string into a file-control block ae a 
drive, filename, and extension. 


Include File <dos.h> 


command_line (in): String to parse in search of the 
filename 
filecontrol__block (in): Structure into which drive, file- 
name, and extension are placed 
al__registers (in): AL register setting for DOS in- 
| terrupt: 
0 Scan past leading separators 
2 Match FCB drive specifier 
with drive found in the com- 
mand line 
4 Match FCB filename to file- 
name found in the command 
line 
8 Match FCB file extension to 
the file extension found in the 
command line 


Example 


result = parsfnm (commline, &file—_contro!— block): 


Note If successful, parsfnm returns a pointer to the first byte 
following the filename. Otherwise, parsfnm returns NULL. 
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unt peek (int segment, 
nt offset); 


Function Returns the integer value contained in the memory loca- 
tion pointed to by the specified segment and offset value. 


Include File <dos.h> 


segment (in): Segment address desired 
offset (in): Offset address desired 
Example 


char_—and—color = peek (0xb800, 0); 


ant peekb (ant segment, 
int offset); 


Function Returns the byte value contained in the memory loca- 
tion pointed to by the specified segment and offset value. 


Include File <dos.h> 


segment (in): Desired segment address 
offset (in): Desired offset address 
Example 


color = peekb (0xb800, 1); 
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void perror (char *string); 


Function Displays an error message to stderr and describes the 
error associated with the most recent system call. 


Include File <stdio.h> 


string (in): The name of the program encountering 
the error 


Example 


perror ("“FILECOPY”); 


void far preslice (int x—loe, 
y—loc, ant start—angle, 
mt end—angle, int radius); 
Function Draws a pie slice on your screen at the specified x and y 


location by using the starting and stopping angles given with a 
radius as provided. Fill the pie slice with the current fill pattern 


and color. 
x—loc, y__loc (in): Location at which to draw 
start_angle (in): Starting angle of the pie arc 
(0-360) 
end__angle (in): Ending angle of the pie arc (0-360) 
radius (in): Desired radius in pixels 
Example 


pieslice (100, 100, 45, 90, 30); 
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Note pieslice uses the current fill pattern and color. 


void poke (int segment, 
ant offset, int value); 


Function Places the specified integer value into the memory loca- 
tion given by segment and offset. 


Include File <dos.h> 


segment (in): Segment address of the desired memory 
location | 
offset (in): Offset address of the desired memory lo- 
cation 
value (in): Value to place into the memory location. 
Example 


poke (0xB800, 0, 0x4807); 


void pokeb (int segment, 
nt offset, int value); 


Function Places the specified byte value into the memory loca- 
tion given by segment and offset. 


Include File <dos.h> 


segment (in): Segment address of the desired memory 
location 
offset (in): Offset address of the desired memory 


location 
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value (in): Byte value to place into the memory 
location 


Example 


pokeb (0xB800, 0, ‘a’); 


double poly (double x, 


ant degree, 
— double ae 


Function Generates a polynomial of degree n from the coefficients 
specified in poly__array. Evaluates the polynomial for the value 
specified in x and returns the result. 


Include File <math.h> 


x (in): Value for which to evaluate the poly- 
| nomial 
degree (in): Degree of the polynomial 
poly__array (in): Array containing the polynomial coef- 
ficients 
Example 


result = poly (5, 3, coeffs); 


double pow (double value, 
double power); 


Function Returns the result of value raised to the specified 
power. 
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Include File <math.h> 


value (in): Value to raise to the specified power 
power (in): Desired power 
Example 


result = pow (5, 2); 


double pow10 (int power); 


Function Returns the result of the value 10 raised to the specified 
power. 


Include File <math.h> 


power (in): Power to raise the value of 10 to 


Example 


one__hundred = pow10 (2); 


ant printf (char *format—sequence |, 
argument... ]); 


Function Provides formatted output to stdout. 
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Include File <stdio.h> 


format__sequence (in): Control characters that specify the 
format of the data to be output 
argument (in): Data to be output 


Example 


printf (“DATA %d %f %s\n”, 5, 33.44, str—var); 


Note The printf routine supports the following control sequences: 


%d Signed integer 


—%I Signed integer 
— %O Octal value 
%U Unsigned integer 
%X Unsigned hexidecimal 
%X Unsigned hexidecimal 
%E Floating-point value 
%E Floating-point value in [—]d.dddd e [+/—]ddd 
% Floating-point value in either f or e format, de- 
pending upon value or precision | 
%c Character 
%S String value 
%% % character is printed 
%n Pointer to the type int 
%p Pointer value 


You can also append the following input size modifiers: 


Long value 
Short integer 
Far pointer 
Near pointer 


Ze 
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unt pute (int character, 
FILE *stream); 


Function Outputs the specified character to the file associated 
with stream. 


Include File <stdio.h> 


character (in): Character to be output 
stream (in): File to which character is to be output 
Example 


result = pute (‘A’, stdout); 


Note If successful, pute returns the value of the output character. 


mt putch (int character); 


Function Outputs the specified character to BDOS or video 
memory. 


Include File <conio.h> 


character (in): Character to be output 


Example 


(in): result = putch(character); 


Note putch writes its output to the current window. 
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int putchar(int character); 


Function Outputs a character to the stdout stream. 


Include File <stdio.h> 


character (in): | Character to be output 


Example 
result = putchar('A’); 


Note The putchar routine is a C macro defined as putc (character, 
stdout). 


int putenv (char *environment—entry); 


Function Places an entry in the current environment. 


Include File <stdlib.h> 


environment—entry (in): Character string to be placed 
into the current environment 


Example 


result = putenv ("FILE=MYFILE”); 
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Note If successful, putenv returns the value 0. If an error occurs, 
putenv returns —1. DOS assigns a copy of the current DOS envi- 
ronment to the executing program. Therefore, putenv does not place 
an entry in the actual DOS environment, but rather the program’s 


copy. 


void far putimage (int x—loc, 
y—loc, void far *buffer, 
ant operation); 


Function Places a graphics image previously saved by getimage 
back on the screen display at the specified location. 


Include File <graphics.h> 


x__loe, y__loe (in): Coordinates of upper-left corner of 
the image : 
buffer (in): Buffer containing the graphics 
Image 
operation (in): Specifies how the pixels are placed 


back onto the screen: 
Straight copy 

1 Exclusive or 

2 Inclusive or 

3 And 

4 Inverse source copy 


co) 


Example 


putimage (100, 100, box, 0); 
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void far putpixel (int x—loe, 
ant y—loc, int pixel—color); 


Function Displays a pixel of the specified color at the x and y loca- 
tion given. 


Include File <graphics.h> 


x_loe, y—loe (in): Location at which to display the 
, pixel 
pixel__color (in): Color of the pixel 
Example 


putpixel (100, 100, 1); 


wnt puts (char estring); 


Function Writes a string to the stream associated with stdout. 


Include File <stdio.h> 


string (in): Character string to be displayed 


Example 


puts ("String to output”); 


Note If successful, puts returns the last character written. If an 
error occurs, puts returns EOF. 7 
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ant puttext (int left—corner, 

ant top—corner, 

ant right—corner, 

ant bottom—corner, void *buffer); 


Function Copies text stored in a buffer back to the screen display. 


left__corner (in): Specifies the x coordinate of the 
upper-left corner of the region to 

restore 
top—corner (in): Specifies the y coordinate of the 
upper-left corner of the region to 

restore 
bottom—corner (in): Specifies the y coordinate of the 
lower-right corner of the region to 

restore 
right_corner (in): Specifies the x coordinate of the 
lower-right corner of the region to 

~ restore 


Example 


status = puttext (10, 10, 20, 20, buffer); 


Note If successful, puttext returns 1; otherwise, it returns 0. 


wnt putw (int word, 
FILE *stream); 


Function Outputs a word (16 bit) value to the specified file stream. 
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Include File <stdio.h> 


word (in): 16-bit value to be output 
stream (in): File stream to output to 
Example 


result = putw (1024, fp); 


Note If successful, putw returns the integer value output. 


void qsort (void *base—address, 
ant num—elements, 

unt width, | 

ant (*compare—function)()); 


Function Uses quick sort to sort the items in an array. 


Include File <stdlib.h> 


base_address (in): Address of the first element in the 


array 
num_—elements (in): | Number of array elements 
width (in): Number of bytes in each element 


-compare_—function (in):Function to be used to compare 
array elements 
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Example 


qsort (my—array, 10, sizeof(float), float—compare); 


Note This quick sort is a generic quick sort algorithm that works 
for all array types. See Chapter 11 for more information on the com- 
parison functions. 


ant rand(void); 


Function Returns a random number. 
Include File <stdlib.h> 


Example 


random = rand (); 


Note To reseed the random number generator, use srand. 


wnt randbrd (struct feb *file—control—block, 
ant num—records); 


Function Using a file control block, reads the number of records 
specified by num-__records. 
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Include File <dos.h> 


file—control_block (in): Pointer to a file control 
: block that contains the file 
characteristics 
num__records (in): Number of records to read 
Example 


result = randbrd (&file—control—block, 5); 


Note: The randbrd routine returns one of the following 
values: _ | 

All records were read 

End of file reached (all records read) 

Incomplete records are read 

Eind of file reached (records incompletely read) 


Whe © 


ant randbwr (struct feb *file—control—block, 
ant num—records); 


Function Using a file control block, writes the number of 
records specified by num_—records. 


Include File <dos.h> 


file—_control__block (in): Pointer to a file control 
block that contains the file 

| characteristics | 

num__records (in): Number of records to write 
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Example 


result = randbwr (&file—control—block, 5); 


Note The randbwr routine returns one of the following values: 


0 All records written 
1 Insufficient disk space 


wnt random (int boundary); 


Function Returns a random number between 0 and the value of bound- 
ary —1. 


Include File <stdlib.h> 
boundary (in): This value —1 is the highest value rand 


can return 


Example 


start = random (10); 


Note The random routine is defined as rand % num. 
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void randomize (void); 


Function Initializes the random number generator. 
Include File <stdlib.h> 


Example 
randomize (); 


Note The randomize routine initializes the random number genera- 
tor with a random value. 


ant —read (int file—handle, 
void *buffer, int num—bytes); 


Function Reads the specified number of bytes from the file asso- 
ciated with the file handle. 


Include File <jo.h> 


file__handle (in): File handle associated with the desired 
file 

buffer (in): Location to read the data into 

num_—_bytes (in): Number of bytes to read 


Example 


result = —read (filehandle, buffer, 256); 
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Note If successful, __read returns the number of bytes read. If an 
error occurs, —read returns —1, and on end of file, it returns the value 
0. The __read routine directly calls a DOS system service. The maxi- 
mum number of bytes this routine can read is 65,534. 


mt read (int file—handle, 
void *buffer, int num—bytes); 


Function Reads the specified number of bytes from the file asso- 
ciated with the file handle. 


Include File <jio.h> 


file__handle (in): File handle associated with the 
desired file 


buffer (in): Location to read the data into 
num__bytes (in): Number of bytes to read 
Example 


result = read (filehandle, buffer, 256); 


Note If successful, read returns the number of bytes read. If an 
error occurs, read returns —1, and on end of file, it returns the value 
0. The maximum number of bytes this routine can read is 65,534. 


void *realloe (void *po inter, 
unsigned newsize—in—bytes); 


Function Modifies the amount of a previously allocated section of 
memory. 
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Include File <alloc.h> 


pointer (in): | Pointer to the previously allocated 
memory 
newsize_—in__bytes (in): Size desired for the memory block 
Example 


ptr = realloc (ptr, 1024); 


Note If successful, realloc returns a pointer to the new block of 
allocated memory. If the request is unsuccessful, realloc returns 
NULL. 


void far rectangle (int left—corner, 
ant top—corner, 

unt right—corner, 

ant bottom—corner); 


Function Draws a rectangle with the specified corners. 


Include File <graphics.h> 


left_corner (in): Specifies the x coordinate of the 
upper-left corner of the rectangle 
top—corner (in): Specifies the y coordinate of the 


: upper-left corner of the rectangle 
bottom—corner (in): Specifies the y coordinate of the 
lower-right corner of the rectangle 
right—corner (in): Specifies the x coordinate of the 
lower-right corner of the retangle 
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Example 


rectangle (10, 10, 20, 30); 


Note The rectangle routine uses the current line thickness and 
drawing color. 


int registerbgidriver (void (*driver)(void)); 


Function Registers linked-in graphics driver code. 
Include File <graphics.h> 


Example 


status = registerbgidriver (KGA—driver); 


Note If registerbgidriver encounters an error, it returns the corre- 
ponding error code; otherwise, it returns the value 0. 


int registerbgifont (void(*font)(void)); 


Function Registers a linked-in graphics font. 


Include File <graphics.h> 
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Example | 


status = registerbgifont (big—font); 


Note If registerbgifont encounters an error, it returns the corre- 
sponding error code; otherwise, it returns the value 0. 


nt rename (char *oldname, 
char *newname); 


Function Renames an existing file as specified. 


Include File <stdio.h> 


oldname (in): Current name of the file to rename 
newname (in): Desired name of the file to rename 
Example 


result = rename ("TEST.C”, "TEST.SAV”): 


Note If successful, rename returns the value 0. If an error occurs, — 
rename returns the value —1. 


void far restorecrtmode (void); 


Function Restores the screen mode to the setting that was in effect 
prior to a call to initgraph. 


Include File <graphics.h> 
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Example 


restorecrtmode (); 


wnt rewind (FILE *stream); 


Function Resets the file pointer of the specified stream to the 
beginning of a file. 


Include File <stdio.h> 


stream (in): File stream associated with the file to reset 


Example 


result = rewind (fp); 


Note If successful, rewind returns the value 0. If an error 
occurs, rewind will return a nonzero result. 


int rmdir (char *directory—name); 


Function Removes the specified DOS directory. 


Include File <dir.h> 


directory__name (in): Name of the DOS subdirectory to 
remove 
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Example 


result = rmdir (”QUICKC”); 


Note The rmdir routine cannot remove a directory if the directory 
contains files, the directory is the current directory, or the directory is 
the root directory. If successful, rmdir returns the value 0. Otherwise, 
rmdir returns the value —1. 


unsigned —rotl (unsigned value, 
ant num—shifts); 


Function Rotates an unsigned value to the left the number of shifts 
specified. , 
Include File <stdlib.h> 


value (in): Unsigned value to shift left 
num _—shifts (in): Number of shifts to perform 


Example 


result = —rotl (address, 16); 


unsigned _rotr (unsigned value, 
ant num—shifts); 


Function Rotates an unsiened value to the right the number of 
shifts specified. 
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Include File <stdlib.h> 


value (in): Unsigned value to shift right 
num_—shifts (in): Number of shifts to perform 


Example 


result = _rotr (address, 16); 


char *sbrk (int increment); 


Function Adds the number of bytes specified to the data space 
allocation (see brk). 


Include File <alloc.h> 


increment (in): Number of bytes to add to the data 
space 


Example 


result = sbrk (1024); 


Note If successful, sbrk returns the previous brk value. 


ant scanf (char format— 
sequence [,argument. . . }); 


Function Perform formatted input from stdin. 
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Include File <stdio.h> 
format__sequence (in): Control sequence specifying the out- 
| put format 
argument (in): Data to be read 
Example 
num__tfields = seanf ("%d %d %f\n", &a, &b, &c); 


Note The scanf routine returns the number of fields successfully 
filled. See printf for the control-sequence formatting characters. 


char *searchpath (char *filename); 


Function Searches the DOS PATH for a file that matches the 
name given, and if the file is found, returns a complete DOS path- 
name to the file. 


Include File <dir.h> 


filename (in): Name of the DOS file to search for 


Example 


pathname = searchpath (“TURBOC.DAT”); 
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Note If successful, searchpath returns the complete pathname. If 
the file is not found, searchpath returns the value NULL. 


void segread (struct REGS *segment— 
registers); 


Function Returns the current values of the segment registers. 


Include File <dos.h> 


segment__registers (in): Structure containing the DOS 
segment registers 


Example 


segread (&segment__registers); 


void far setactivepage (int page— 
number); 


Function Specifies the active video display page for graphics 
output. 


Include File <graphics.h> 


- page_number (in): Desired video display page number 


Example 


setactivepage (2); 
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Note Only EGA, VGA, and Hercules graphics cards support 
multiple graphics display pages. 


void far setallpalette 
(struct palettetype far *palette); 


Function Defines the colors of the palette. 


Include File <graphics.h> 


palette (in): Structure containing the palette 
colors: 
struct palettetype { 
unsigned char size; 
signed char colors 
([MAX—COLORS+1]; 
3 


Example 


setallpallette (my —palette); 


void far setbkcolor (int background—color); 


Function Sets the current graphics background color. 
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Include File <graphics.h> 


background_—color (in): Desired color from your current 
- palette 


Example 


setbkcolor (1); _ = -“ 


nt setblock (int segment, 
ant newsize—in—bytes); 


Function Modifies the size of a previously allocated DOS 
segment. 


“Include File <dos.h> 


segment (in): Previously allocated DOS 
segment 
newsize__in__bytes (in): Desired segment size in bytes 


Note If successful, setblock returns the value —1. If an error 
occurs, setblock returns the value of the largest available block. 


void setbuf (FILE *stream, 
char *buffer); 


Function Assigns a new buffer to be used for file I/O to the 
specified stream. 
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Include File <stdio.h> 


stream (in): File stream to be buffered 
buffer (in): | Memory location to be used for buffering 


Example 
- setbuf (fp, char—array); 


Note Ifthe buffer specified is NULL, I/O to the file stream is 
not buffered. 


ant setcbrk (int status); 


Function Enables/disables control-break checking. 


Include File <dos.h> 


status (in): Desired control break setting: 
0 Disables control-break checking 
1 Enables control-break checking 


Example 


result = setcbrk (1); 


Note The setcbrk routine returns the current state of control- 
break checking. 7 
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void far seteolor (int color); 


Function Sets the current drawing color. 


eolor (in): Desired drawing color from your cur- 
rent palette 


Example 


setcolor (2); 


void setdate (struct date *current—date); 


Function Sets the current DOS system date. 


Include File <dos.h> 


current__date (out): Structure containing the current sys- 
tem date: 
struct date { 
int da__year; 
char da__day; 
char da__mon; 


} ? 


Example 


status = setdate (&current—date); 
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wnt setdisk (int disk_—adrvve); 


Function Sets the disk drive as specified. 


Include File <dir.h> 
disk__drive (in): Desired disk drive (A = 0,B=1, 
C= 2...) 
Example 
result = setdisk (1); 


Note The setdisk routine returns the number of disk drives 
available. | 


void setdta (char far *disk— 
transfer—address); 


Function Defines a new disk transfer address. 


Include File <dos.h> 


disk__transfer__address (in): Address of the desired disk 
| transfer 


Example 


| setdta ((char far *) buffer); 
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setfillpattern (char far *fill—pattern, 
ant color); 


Function Selects a user-defined fill pattern for graphics mode. 


fill__pattern (in): Array containing desired fill 
pattern 
color (in): Desired fill color from current 
palette 
Example 


setfillpattern (xxx, 1); 


void far setfillstyle (int fill—_style, 
ant color); 


Function Selects a fill style and color. 


fill_pattern (in): Desired fill style: 
Empty fill 
Solid fill 
2 Line fill - 
3 Left-slash fill / 
4 Thick left-slash fill 
5 Backslash fill \ 
6 Thick backslash fill 
7 Light hatch fill 
8 Heavy crosshatch fill 
9 Interleaving line fill 
10 Wide-spaced dot fill 
11 Close-spaced dot fill 
color (in): Desired fill color from your current 
palette 
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Example 


setfillstyle (3, 1); 


wnt setftume (int file—handle, 
struct ftume *file—stamp); 


Function Sets a file’s date and time stamp. 


Include File <dos.h> 


file—handle (in): File handle associated with the de- 
sired file 
file_stamp (out): Structure containing the file’s date 
| and time: 
struct ftime { 
unsigned ft__tsec:5; 
unsigned ft__min:6; 
unsigned ft__hour:5; 
unsigned ft__day: 5; 
unsigned ft__month:4; 
unsigned ft__year: 7; 


Example 


status = setftime (filehandle, &file—_stamp); 


Note If successful, setftime returns the value 0. 
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unsigned far setgraphbufsize 
(unsigned buffer—size); 


Function Defines the size of the internal graphics buffer. 


buffer__size (in): Size, in bytes, of the buffer desired 


Example 


setgraphbufsize (9182); 


Note You must call setgraphbufsize before initgraph. 


void far setgraphmode (int graphics—mode); 


Function Selects the current graphics mode. 


Include File <graphics.h> 


graphics_mode (in): Desired graphics mode 


Example 


setgraphmode (CGA); 


Note See the graphics.h file for graphics modes. 


ant setymp Qmp—buf task—state); 


617 


Function Marks the location for a future goto that is outside the 


current block of code. 
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Include File <setjmp.h> 


task__state (in): Buffer storing the values of CS, DS, 
| ES, SS, SI, DI, SP, FP, and flags 


Example 


setjmp (&task_state); 


Note See the longjmp routine. 


void far setlinestyle (int line—style, 
unsigned pattern, 
ant thickness); 


Function Sets the current width and line style. 


Include File <graphics.h> 


line__style (in): Desired line style: 

0 Solid line 

1 Dotted line 

2 Centered line 

3 Dashed line 

4 User-defined line style 
pattern (in): Desired line pattern if user-de- 

| fined pattern is used 

thickness (in): Desired thickness for the line: 


1 One-pixel thickness 
3  Three-pixel thickness 
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Example 


setlinestyle (0, 0, 1); 


void setmem (void *address, 
nt num—bytes, char letter); 


Function Assigns the number of occurrences of the specified let- 
ter to the address given. 


Include File <mem.h> 


address (in): Memory address to assign the charac- 
ters to 
num_—bytes (in): Number of bytes to assign the letters 
to 
letter (in): Value to assign to the memory loca- 
tions 
Example 


setmem (ptr, 255, 'A’); 


wnt setmode (int [HEROES 
unsigned mode); 


Function Sets the file associated with the given handle to the mode 
(text or binary) as specified. 


Include File <io.h> 


filehandle (in): File handle of the file to modify 
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mode (in): Desired mode: 
O__BINARY Binary file 
O_TEXT Text file 


Example 


setmode (fp, O—BINARY); 


Note If successful, setmode returns the value 0. Otherwise, it 
returns the value —1. | 


void far setpalette (int index, 
ant color); 


Function Assigns an actual color to an index in the current 
palette. | 


Include File <graphics.h> 


index (in): Index into the palette that you are as- 
| signing a color to 
color (in): Actual color value assigned to the pal- 
ette index 
Example 


setlinestyle (1, 4); 


void far settextzustify (int horizontal, 
ant vertical); 


Function Specifies text justification. 
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Include File <graphics.h> 


horizontal (in): Specifies how horizontal text is to 
be justified: 
0 Left justify 
1 Center justify 
2 right justify 
vertical (in): Specifies how vertical text is to be 
justified: 
0 Bottom justify 
1 Center justify 
2 ‘Top justify 


Example 


settextjustify (1, 1); 


void far settextstyle (int font, 
ant direction, int size); 
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Function Specifies the graphics mode text font, direction, and size. 


Include File <graphics.h> 


font (in): Specifies desired font: 
0 8&8 X 8 bit-mapped font 
1 Triplex font 
2 Small font 
3 Sans serif font 
4 Gothic font 
direction (in): Specifies how text is to be written: 
0 Horizontal left to right 
1 Vertical bottom to top 
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size (in): Specifies font size (1-10): 
1 8x8 
2 16X 16 
Example 


settextstyle (0, 0, 1); 


void settime (struct time “system —time); 


Function Sets the current system time. 


Include File <dos.h> 


system_time (out): Structure containing. the current 
system time: 
struct time { 
unsigned char ti__min; 
unsigned char ti__hour; 
unsigned char ti__hund; 
unsigned char ti__sec; 


Example 


settime (&current—time); 
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type (in): Specifies the type of buffering de- 
sired: 
—IOFBF Full file buffer for input/ 
output 
_IOLBF Line buffer the file 
_IONBF No buffering for the file 
num__bytes (in): Number of bytes to allocate for the 
buffer 


Example 


setvbuf (fp, char—array, —IONBF, 0); 


Note Ifthe buffer specified is NULL, I/O to the file stream is not 
buffered. 


void setvect (int nterrupt—number, 
void interrupt (*service—routine) ()); 


Function Defines a new interrupt handler for the specified 
interrupt. 


Include File <dos.h>_ 


interrupt_number (in): Interrupt to define a new ser- 
vice routine for 

service_routine (in): Function serve as the new 
interrupt handler 
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void far setusercharsize (int «mult, 
ent «div, vnt ymulet, 
ant ydiv); 


Function Specifies graphics mode character magnification. 


Include File <graphics.h> 


xmult, xdiv (in): Width scaling factors 
ymult, ydiv (in): Height scaling factors 


Example 


setusercharsize (2, 1, 3, 2); 


Note These values are only active when you have called the settext- 
style routine with charsize equal to 0. 


void setubuf (FILE *stream, 
char *buffer, int type, 
unsigned num—bytes); 


Function Assigns a new buffer to be used for file I/O to the speci- 
fied stream. 


Include File <stdio.h> 


stream (in): File stream to be buffered 
buffer (in): Memory location to be used for buf- 
fering 
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Example 


setvect (5, my—print—routine); 


void setverify (int state); 


Function Enables or disables disk verification. 


Include File <dos.h> 


state (in): Desired disk verification state: 0 dis- 
ables and 1 enables disk verification 


Example 


setverify (1); 


void far setviewport (int left—corner, 
ant top—corner, 

ant right—corner, int 

bottom—corner, int clip); 


Function Defines the current viewport for graphics output. 


Include File <graphics.h> 


left__corner (in): Upper-left corner x viewport co- 
ordinate 
top—corner (in): Upper-left corner y viewport co- 


ordinate 
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right—corner (in): Lower-right corner x viewport co- 


ordinate 
bottom—corner (in): Lower-right corner y viewport co- 
| ordinate | 7 
clip (in): Specifies whether values outside of 


the viewport are clipped. If clip is a 
nonzero value, clipping is enabled 


Example 


setviewport (10, 10, 200, 200, 1); 


void far setvisualpage (int page—number); 
Function Sets the video display page to be displayed. 


Include File <graphics.h> 


page__number (in): Desired video display page 
number 


Example 


setvisualpage (2); 


Note Only EGA, VGA, and Hercules graphics cards support mul- 
tiple graphics display pages. 


double sin (double value); 


Function Returns the trigonometric sine of the specified value. 
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Include File <math.h> 


value (in): Value to return the sine of 


Example 


result = sin (p1); 


double sinh (double value); 


Function Returns the hyperbolic sine of a value. 


Include File <math.h> 


value (in): Value to return the hyperbolic sine of 


Example 


result = sinh (value); 


void sleep (unsigned seconds); — 
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Function Suspends the current application for the interval of time 


specified. 


Include File <dos.h> 


seconds (in): Number of seconds to suspend the 
application for 


Example 


sleep (10); 
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void sound (unsigned frequency); 
Function Turns on the IBM PC speaker at the specified frequency. 


Include File <dos.h> 


frequency (in): Desired frequency for the speaker 
sound 
Example 
sound (14); 


int spawn...(int mode, 
char *command, — 
char *arg [,...], NULL); 


Function Creates and executes a child process. 


Include File <process.h> 


mode (in): Action taken after spawn call: 
| P_WAIT Wait until child process 
completes 


P__NOWAIT Continue to run as child 
| process runs 

P_OVERLAY Overlay child process 

in memory previously 

contained by the parent 


command (in): Complete DOS pathname of the com- 
mand to execute 
arg (in): Command-line argument passed to the 


child process 
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Example 


spawn (P_WAIT, "BACKUP", "C:*.*") "A:", NULL); 


Note Several versions of spawn exist: 


spawnl Search only the root or current di- 
rectory 

spawnle Same as spawnl; also allows environ- 
ment to be passed as a parameter 

spawnp Searches the DOS PATH command 

spawnv Command-line arguments are passed as 
a single array of pointers 

spawnlp 

spawnlpe 

spawnve 

spawnvp 

spawnvpe 


See the dos.h file for the calling sequence of each command. If suc- 
cessful, spawn returns the value 0. 


wnt sprintf (char *string, 
char *format—sequencef,argument.. . ]); 


Function Writes formatted output to a string, as opposed to a file 
stream. 


Include File <stdio.h> 


string (out): Character string containing the for- 
| matted output 
format_sequence (in): Control sequence that specifies 
how to format the data 
argument (in): Data to be output 
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Example 


result = sprintf (str, "%d", age); 


Note The sprintf routine returns the number of bytes output, not 
including the NULL terminal. 


double sqrt (double value); 


Function Returns the square root of a value. 


Include File <math.h> 


value (in): ~ Value to return the square root of 


Example 


five = sqrt (25.0); — 


void srand (unsigned seed); 


Function Initializes or seeds the random number generator. 


Include File <stdlib.h> 


seed (in): Desired seed for the random number 
generator | 
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Example 


srand (time(&current)); 


wnt sscanf (char *string, 
char format— 
sequence [,argument. . . }); 


Function Performs formatted input from a string, as opposed to 
a file stream. 


Include File <stdio.h> 


string (in): | Character string to read from 
format_sequence (in): Control sequence specifying the 
output format 
argument (in): Data to be read 
Example 


num_—tfields = sscanf (str, "%d %d %f\n”", &a, &b, &c); 


Note The sscanf routine returns the number of fields successfully 
filled. 


int stat (char *pathname, 
struct stat *stat—info); 


Function Returns information about the specified file. 
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Include File <stat.h> 


pathname(in): Pathname of the desired file 
stat_info (out): Structure containing the file in- 
formation 
Example 


result = stat ("TEST.C”, &stat— info); 


Note If successful, stat returns the value 0. Otherwise, it returns 
the value —1. | 


unsigned wnt —status87 (void); 


Function Returns the current math coprocessor status word. 
Include File <float.h> 


Example 


status = —status87(); 


Note The float.h file defines the return value of —status87. 
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int stime (long *seconds); 


Function Sets the current system time to the number of seconds 
since 00:00 01/01/1970. 
Include File <time.h> 


seconds (in): Number of seconds since 
00:00 01/01/1970 


Example 


stime (&lots—of—seconds); 


char *stpcpy (char *destination, 
char *source); 


Function Copies the contents of the source string to the 
destination. 


Include File <string.h> 


destination (out): String characters are copied to 
source (in): String characters are copied from 
Example 


result = stpcpy (destination, "STRING TO COPY”); 


Note The stpcpy routine returns destination + the number of 
characters copied. 
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char *streat (char *destination, 
char *source); | 


Function Appends the contents of the source string to the 
destination. 


Include File <string.h> 


destination (out): String characters are appended to 
source (in): String characters are copied from — 
Example 


result = streat (destination, "STRING TO APPEND”); 


Note The streat routine returns destination + the number of 
characters appended. 


strehr (char *string, 
char letter); 


Function Searches a given string for the specified character. 


Include File <string.h> 


string (in): Character string to search 
letter (in): Letter to search for 
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Example 


loc = strchr (str, ’A’); 


Note The strchr routine returns a pointer to the first occurrence of 
the letter specified or the value NULL if the letter does not exist. 


ant stremp (char *s1, 
char *s2); 


Function Compares the contents of two character strings. 


Include File <string.h> 


sl, s2 (in): Character strings to compare 


Example 


result = stremp ("STRING 1”, "STRING 2”); 


Note The strcmp routine returns a value that is 


<O if sl < s2 
=0 if sl == s2 
>0 if sl > s2 


636 TURBO C PROGRAMMER’S LIBRARY 


char *strepy (char *destination, 
char *source); 


Function Copies the contents of the source string to the destination. 


Include File <string.h> 


destination (out): String characters are copied to 
source (in): String characters are copied from 
Example © 


result = strepy (destination, "STRING TO COPY”); 


Note The strcepy routine returns destination. 


wnt strespn (char *s1, 
char *s2); 


Function § Returns an index into s1 that consists entirely of charac- 
ters not contained in s2. 


Include File <string.h> 


s1 (in): String to return the index into ; 
s2 (in): String of characters to compare sl charac- 
ters to | : 
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Example 


index = strespn (str, “ABCDE”); 


char *strdup (char *str); 


Function Returns a pointer to a string containing the same 
sequence of characters as the given string. ? 


Include File <string.h> 


str (in): Character string to duplicate 


Example 


result = strdup ("String to duplicate”); 


Note The strdup routine returns a pointer to the new string, or it 
returns the value NULL if space for the string could not be 
allocated. 


char *—strerror (const char *string); 


Function Generates customized error messages. 


Include File <string.h> 


string (in): Contains the most current error message 


638 TURBO C PROGRAMMER’S LIBRARY 


Example 


result = —strerror (str); 


char *strerror (char *string); - 


Function Returns a pointer to the error message string, allowing 
you to develop customized error messages. 


‘Include File <string.h> 


string (in): Customized error message 


Example | 


result = strerror (Invalid disk drive specified \n”); 


Note If string is NULL, the result of strerror is the error message 
associated with the last system error. 


wnt striemp (char *s1, 
char *s2); 


Function Compares one string to another, ignoring the case of each 
letter. 


Include File <string.h> 


sl, s2 (in): Character strings to compare 
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Example 


result = striemp (“String 1”, “STRING 1”); 


Note The stricmp routine returns a value that is 


<0 if sl < s2 
=0 if sl == s2 
>0 if sl > s2 


unsigned strlen (char *string); 


Function Returns a count of the number of characters in a 
string. 


Include File <string.h> 


string (in): Character string to return the number of 
characters in 


Example 


length = strlen ("String to count”); 


char *strlwr (char *string); 


Function Converts uppercase letters in a string to lowercase. 


Include File <string.h> 
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string (in/out): String to convert to lowercase 


Example 


result = strlwr (string); 


char *strneat (char *destination, 
char *source, 
ant num—bytes); 


Function Appends the contents of the source string to the destina- 
tion. Do not let the resultant string exceed num_—bytes characters. 


Include File <string.h> 


destination (out): String characters are appended to 
source (in): String characters are copied from 
num__bytes (in): Maximum number of bytes in des- 
tination 
Example 


result = streat (destination, src, sizeof (destination)); 


Note The strceat routine returns destination + the number of char- 
acters appended. 
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unt strnemp (char *s1, 
char *s2, int num—bytes ); 


Function Compares the contents of two character strings. 


Include File <string.h> 


Sl, s2 (in): Character strings to compare 
num__bytes (in): Maximum number of bytes 
to examine 
Example 


result = strnemp (sl, "STRING 2”, strlen (s1)); 


Note The strncmp routine returns a value that is 


<0 if sl < s2 
=0 if sl == s2 
>0 if sl > s2 


char *strnepy (char *destination, 
char *source, 
num—bytes); 


Function Copies the contents of the source string to the 
destination. 


Include File <string.h> 


_ destination (out): String characters are copied to 
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source (in): String characters are copied from | 
num_bytes (in): Maximum number of bytes to copy to 
destination 
Example 


result = strnepy (destination, sl, sizeof (destination)); 


Note The strncpy routine returns destination. 


int strniemp (char *s1, 
char *s2, int num—bytes ); 


Function Compares the contents of two character strings, ignor- 
ing the case of each letter. © | 


Include File <string.h> 


sl, s2 (in): Character strings to compare 
num_bytes (in): Maximum number of bytes to 
examine 
Example 


result = strnicmp (sl, "STRING 2”, strlen (s1)); 


Note The strnicmp routine returns a value that is 


<0 if sl < s2 
=0 if sl == s2 
>0 if sl > s2 
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char *strnset (char *string, 
char character, 
ant max—bytes); 


Function Assigns max—bytes occurrences of the specified charac- 
ter to the given string. 


Include File <string.h> 


string (out): Character string to assign the charac- 
ters to 
character (in): Character to assign to the string 


max__bytes (in): Number of characters to assign 


Example 


result = strnset (str, ‘A’, sizeof(str)); 


char *strpbrk (char +81, 
char *s2); 


Function Scans s2 for the first occurrence of a character in sl. 


Include File <string.h> 


s2 (in): Search to scan 
sl (in): Set of letters to search for 
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Example 


result = strpbrk (s1, s2); 


Note The strpbrk routine returns a pointer to the first character 
in s2 that occurs in sl. If no characters occur, strpbrk returns the 
value NULL. 


char *strrchr (char *str, 
char character); 


Function Searches a string for the rightmost occurrence of the 
specified character. 


Include File <string.h> 


str (in): String to search 
character (in): | Letter to search for 
Example 


index = strrchr (str, 'z’); 


Note Ifthe letter does not occur in the string, strrchr returns the 
value NULL. If the letter occurs, strrchr returns a pointer to the 
rightmost location. 
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char *strrev (char *string); 


Function Reverses the characters contained in the string. 


Include File <string.h> 
string (in/out): String containing the characters to 
reverse 
Example 


result = strrev (str); 


char *strset (char *string, 
char character); 


Function Assigns each of the characters in a string to the charac- 
ter specified. 


Include File <string.h> 


string (out): Character string to assign the letter to 
character (in): Character to assign to the string 
Example 


result = strset (str, 'A’); 
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char *strstr (char *s1, 
char *s2); 


Function Searches the s1 string for the first occurrence of the s2 
string. 


Include File <string.h> 


sl (in): String to search for 
sl (in): Character string to search 
Example 


index_ptr = strstr ("This is it”, "is”): 


Note If the string is found, strstr returns a pointer to the first | 
occurrence of the string in s2. If the string is not found, strstr 
returns the value NULL. 


double strtod (char *string, 
char **end); 


Function Converts a character string representation of a floating- 
point value to a value of type double. 
Include File <string.h> 


string (in): Character string to convert 
end (out): Character that the conversion stopped at 
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Example 


double—result = strtod (183.344”", &end); 


Note The strtod routine stops at NULL or at the first character 
that cannot be converted. If *end is not equal to NULL, the string 
contained invalid characters. 


char *strtok (char *s1, 
char *s2); 


Function Searches the character string sl for a set of tokens 
defined in s2. 


Include File <string.h> 


Sl (in): Character string to search 
s2 (in): String of tokens 
Example 


result = strtok (s1, s2); 


Note Ifa token is found, strtok returns a pointer to that location. Other- 
wise, strtok returns the value NULL. 
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long strtol (char *string, 
char **end, int radix); 


Function Converts a character string representation of a long 
value to a value of type long. 


Include File <string.h> 


string (in): Character string to convert 

end (out): Character that the conversion stopped at 

radix (in): Base of the value contained in the string 
Example 


long—result = strtol ("183344L”, &end, 10); 


Note The strtol routine stops at NULL or at the first character 
that cannot be converted. If *end is not equal to NULL, the string 
contained invalid characters. 


unsigned long strtoul (const char *sty, 
char **end—pointer, 
ant radix); 


Function Converts a string containing an ASCII representation of 
a value to an unsigned long integer. 


Include File <stdlib.h> 


str (in): String containing ASCII represen- 
tation of the value 
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end_pointer (out): Pointer to the last character used 


in the conversion 
int radix (in): Base of ASCII representation (2, 8, 
10, 16) 
Example 


result = strtoul ("56333”, end—pointer, 10); 


char *strupr (char *string); 
Function Converts a character string to uppercase. 


Include File <string.h> 


string (in): Character string to convert to uppercase 


Example 


result = strupr (s1); 


void swab (char *s1, char *s2, 
ant num—bytes); 


Function Swaps the specified number of bytes from one string to 
another. 


Include File <stdlib.h> 


sl,s2 (in/out): Strings containing the bytes to exchange 
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Example 


swab (s1, s2, sizeof (s1)); 


ant system (char *~DOScommand); 


Function Invokes a DOS command from within your program. 


Include File <stdlib.h> 


DOScommand (in): DOS system command to execute 


Example 


result = system ("DIR”); 


Note The value returned is that generated by COMMAND.COM. 


double tan (double value); 


Function Returns the trigonometric tangent of the specified value. 


Include File <math.h> 


value (in): Value to return the tangent of 
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Example 


result = tan (pi * x); 


double tanh (double value); 
Function Returns the hyperbolic tangent of the specified value. 
Include File <math.h> 


value (in): Value to return the tangent of 


Example 


result = tanh (pi * x); 


long tell (int filehandle); 
Function Returns the file pointer position for the specified file. 


Include File <io.h> 


filehandle (in): File handle associated with the desired 
file 


Example 


loc = tell (filehandle); 
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void textattr (int attribute); 


Function Sets foreground and background text mode colors and 
attributes. 


Include File <conio.h> 


attribute (in): Specifies the foreground and back- 
ground colors. First four LSBs are 
foreground color; next three LSBs 
are background color; MSB is blink 
attribute enable bit. 


Example 


textattr (OxA 1); 


Note The following colors are defined in conio.h: 


Foreground and Background: 


0 Black '5 ~ Magenta 
1 Blue 6 Brown 
2 Green | 7 Light gray 
3 Cyan 8 Dark gray 
4 Red 
Foreground Only: 
9 Light blue 13 Light magenta 
10 + Light green 14 Yellow 
11 Light cyan 15 White 
12 Light red ~~ 128 Blink 


void iti aaaiclaaiaa (ant background — 
color); 


- Function Selects the desired background color. 
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Include File <conio.h> 


background—color (in): Desired background color (0-7) 


Example 


textbackground (38); 


Note See conio.h for color definitions. 


void textcolor (int color); 


Function Selects a new character color for text mode. 


Include File <conio.h> 


color (in): Desired color 


Example 


textcolor (1); 


unt far textheight (char far *string); 


Function Returns the pixel height of a string. 
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Include File <graphics.h> 


string (in): String of interest | 


Example 


result = textheight (“TEXT”); /* height by default is 8 */ 


void textmode (int desired—mode); 


Function Selects a specific text video mode. 


Include File <conio.h> 


desired__mode (in): Desired text mode: 


= Last text mode selected 
0 Black and white, 40 column 
1 Color, 40 column 
2, Black and white, 80 column 
3 Color, 80 column 
7 Monochrome, 80 column 


Example 


textmode (8); 


ant far textwidth (char far *string); 


Function Returns the pixel width of a string. 
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Include File <graphics.h> 


string (in): String of interest 


Example 


result = textwidth (“TEXT”); /* width by default is 8 * 4 */ 


long tume (long *seconds); 


Function Returns the number of seconds that have elapsed since 
00:00 01/01/1970. | 


Include File <time.h> 


seconds (out): Number of seconds since 00:00 01/01/1970 


Example 


result = time (&seconds); 


Note The time routine also returns the number of seconds. 


wnt toaseu (int character); 


Function Converts a given character to a value in the range 
0-127. 
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Include File <ctype.h> 


character (in): Character to convert to ASCII 


Example 


ltr = toascil (extended_ascii—char); 


int —tolower (int character); 


Function Converts an uppercase letter to lowercase. 


Include File <ctype.h> 


character (in): Character to convert to lowercase 


Example 


lower = —tolower(character); 


int tolower (int character); 


Function Converts an uppercase letter to lowercase. 


Include File <ctype.h> 


character (in): Character to convert to lowercase 
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Example 


lower = tolower(character); 
ant —toupper (int character); 
Function Converts a lowercase letter to uppercase. 


Include File <ctype.h> 


character (in): Character to convert to uppercase 


Example 


upper = —toupper(character); 


ant toupper (int character); 


Function Converts a lowercase letter to uppercase. 


Include File <ctype.h> 


character (in): Character to convert to uppercase 


Example 


upper = toupper(character); 


void tzet (void); 
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Function A UNIX-compatibility routine; no function under DOS. 
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Example 


tzet (); 


char *ultoa (unsigned long value, 
char *str, int radix); 


Function Converts an unsigned long int value to its ASCII 
representation. 


Include File <stdlib.h> 


value (in): Long value to convert _ 
str (out): String to contain ASCII representation 
radix (in): Specifies the desired radix (2-36): 2=binary, 


10=decimal, 8=octal, 16=hex, and so on 


Example 


result = ultoa (334114L, str, 10); 


Note The ultoa routine does not return an error status. 


ant ungete (char character, 
FILE *stream); 


Function Pushes a value back into the input file stream. 


Include File <stdio.h> 


character (in): Value to put back into the file stream 
stream (in): File stream desired 
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Example 
result = ungetc (letter, fp); 


Note The ungetc routine returns the value put back into the file 
stream. 


wnt ungetch (char character); 


Function Pushes a value back into the keyboard buffer. 


Include File <stdio.h> 


character (in): Value to put back into the keyboard buffer 


Example 


result = ungetch (letter); 


Note The ungetch routine returns the value put back into the 
keyboard buffer. 


void unixtodos (long uniatime, 
struct date *date—ptr, 
struct tume *tume—ptr); 


Function Converts a UNIX time to DOS format. 
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Include File Aine: 


unixtime (in): Date and time in UNIX format | 
date__ptr (out): Structure containing the DOS format date 
time__ptr (out): Structure containing the DOS format time 


Example 


unixtodos (unixdatetime, &dosdate, &dostime); 
ant unlink (char *DOSfilename); 
Function Deletes the specificed DOS file name. 


Include File <dos.h> 


DOSfilename (in): DOS file to delete 


Example 


result = unlink (’TEST.BAK”); 


Note The unlink routine returns 0 if successful and —1 if an 
error occurs. 
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ant unlock (ant filehandle, 
long offset, 
long num—bytes); 


Function Releases a file-sharing lock previously set by lock. 


Include File <dos.h> 


filehandle (in): File handle of desired file 
offset (in): Location of the first byte to unlock 
num_bytes (in): Number of bytes to unlock 


Example 


result = unlock (filehandle, 1024, 255); 


Note The unlock routine returns 0 if successful and —1 if an 
error occurs. 


usertype va—arg (va—list param, 
usertype); 


Function Returns the next argument in a variable argument list. 


Include File <stdarg.h> 


param (in): Variable-length argument list 
type (in): Data type of the values in the argument list 
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Example 


param = va_—arg (arg—list, int); 


Note The va—arg routine returns N ULL after the last parame- 
ter in the list. 


void va—end (va—list parameter); 


Function Marks the end of a variable argument list. 


Include File <stdarg.h> 


parameter (in): Variable argument list 


Example 


va—end (arg_list); 


void va—start (va—list parameter); 


Function Marks the start of a variable argument list. 


Include File <stdarg.h> 


parameter (in): Variable argument list 
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Example 


va_start (arg—list); 


nt vfprintf (FILE *stream, 
char format—sequence, 
va—list arglist); 


Function Outputs formatted data to an output stream. 


Include File <stdarg.h> 


stream (in): File stream to output to 

format_sequence (in): Control characters that specify how the 
output is to be formatted 

arglist (in): Variable-length argument list to be output 


Example 


result = vfprintf (fp, "%d %c”, arg—list); 


Note The vfprintf routine returns the number of bytes output. 


ant vfscanf (FILE *stream, 
char format—sequence, 
va—list arglist); 


Function Inputs formatted data from an input stream. 
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Include File <stdarg.h> 


stream (in): File stream to input from 

format_sequence (in): Control characters that specify how the 
output is to be formatted 

arglist (in): Variable-length argument list to be output 


Example 


result = vfscanf (fp, "%d %e”, arg_—list); 


Note The vfscanf routine returns the number of fields filled. 


ant vprintf (char format— sequence, 
va—list arglist); 


Function Outputs formatted data to stdout. 


Include File <stdarg.h> 


format__sequence (in): Control characters that specify how the 
output is to be formatted 
arglist (in): Variable-length argument list to be output 


Example 


result = vprintf ("%d %e", arg—list); 


Note The vprintf routine returns the number of bytes output. 
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ant vseanf (char format—sequence, 
va—list arglist); 


Function Inputs formatted data from stdin. 


Include File <stdarg.h> 


format__sequence (in): Control characters that specify how the 
output is to be formatted 
arglist (in): Variable-length argument list to be output 


Example 


result = vseanf ("%d %e”", arg—list); 


Note The vscanf routine returns the number of fields filled. 


ant vsprintf (char *string, 
char format—sequence, 
va—list arglist); 


Function Outputs formatted data to a character string. 


Include File <stdarg.h> 


string (in): Character string to output data to 

format_sequence (in): Control characters that specify how the 
output is to be formatted | 

arglist (in): Variable-length argument list to be output 
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Example 


result = vsprintf (str, "%d %c”, arg—list); 


Note The vsprintf routine returns the number of bytes output. 


ant vsscanf (char *string, 
char format—sequence, 
va—list arglist); 


Function Inputs formatted data from a character string. 


Include File <stdarg.h> 


string (in): Character string to input data from 

format_sequence (in): Control characters that specify how the 
output is to be formatted 

arglist (in): Variable-length argument list to be output 
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Example 


result = vsseanf (str, "%d %e”, arg—list); 


Note The vsscanf routine returns the number of fields filled. 


ant wherex (void); 


Function Returns the x coordinate of the cursor within the cur- 
rent window. 


Include File <conio.h> 


Example 


x_—_loc = wherex (); 


wnt wherey (void); 


Function Returns the y coordinate of the cursor within the cur- 
rent window. 


Include File <conio.h> 
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Example 


y—loc = wherey (); 


void window (int left—corner, 
wnt top—corner, 

ant right—corner, 

wnt bottom—corner); 


Function Defines the active text mode window. 


Include File <conio.h> 


left_corner (in): Upper-left corner x window coordinate 


top—corner (in): | Upper-left corner y window coordinate 
right__corner (in): Lower-right corner x window coor- 
dinate 
bottom_—corner (in): Lower-right corner y window coor- 
dinate 
Example 


window (1, 1, 80, 25); 


int —write (filehandle, 
void *buffer, int num—bytes); 


Function Writes the specified number of bytes to the file asso- 
ciated with the given file handle. 
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Include File <ijo.h> 


filehandle (in): File handle associated with the 
desired file 
buffer (in): Buffer containing the data to 
output 
num__bytes (in): Number of bytes to write to the 
file 
Example 


bytes__wtn = —write (filehandle, buffer, sizeof(buffer)); 


Note If successful, _write returns the number of bytes written; 
otherwise, __write returns the value —1. The maximum number 
of bytes this routine can write is 65,534. 


ant write (filehandle, 
void *buffer, 
ant num—bytes); 


Function Writes the specified number of bytes to the file asso- 
ciated with the given file handle. 


Include File <io.h> 


filehandle (in): File handle associated with the desired 
file | 
buffer (in): Buffer containing the data to output 


num_—bytes (in): Number of bytes to write to the file 
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Example 


bytes—_wtn = write (filehandle, buffer, sizeof(buffer)); 


Note If successful, write returns the number of bytes written; 
otherwise, it returns the value —1. The maximum number of 
bytes this routine can write is 65,534. 


Trademarks 


IBM® International Business Machines Corporation 
MS-DOS® Microsoft Corporation 
Turbo C® Borland International, Inc. 


Index 


A 


Addresses 
incrementing, 64 
offset, 382-383 
segment, 382 
Ampersand (&) operator, 56-57, 61-62 
ANSI driver 
installation of, 224 
operation of, 207-209, 224 
for redefining a DOS function key 
with DOS command, 222-224 
ANSI support, 207-224 
commands for, 208-209 
for keyboard reassignment, 
222-224 
required for multidimensional 


ANSI support, continued 
arrays, 272 
routines for cursor manipulation, 
210-215 
routines for erasing, 215-216 
routines for, 210-224 
routines for screen attributes, 
216-222 
ANSLSYS, 208-209 
ansi__set__mode, 221-222 
append__string, 21, 22-23 
argc, 80-82 
argv, 80-82, 109, 111, 227-228, 305 
array _—_type, 252-253 
for sorting, 274, 284-285 
with quick sort, 310 
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Arrays 
bounds of, 14, 15-17 
fixed size of, 345-346 
manipulation of, 247-272 
multidimensional, 271-272 
of character strings, 12-14, 305-318 
of pointers, 79-80 | 
searching, 274-275 
specifying storage requirements, 
347 
types of, 248-253 
using macros in place of, 269-270 
ASCII character(s), 27, 208 
array of points to display, 79-80 
as white space, 41-43 
ease of, 26-28 
codes, 85, 87, 4381-4383 
representation of floating-point 
value to numeric value, 333-334 
set for framing menu, 408-409 
ASCII code, to display characters, 85, 
87 
ascli__to__float, 333-334 
ascii__to__int, 76-78 
Asterisk (+) | 
as character string, 227-228 
for variable as pointer, 56-57 
ATTR.C, 228-230 
ATTRIB, 228 
aux_char, 144-145 
aux__output, 145-146 
average__value, 254-255 


B 


Binary trees, 366-380 
binary—search, 283-284 
BIOS services 
interface, 191-193 
output routines from, 321 
routines, 193-206 
Blanks | 
preceding string (padding), 33-36 
removing, 41-43 
Borland International, Inc. 
run-time library of, 2-3 
source code of, 3 
Bounds checking, 69 
bsearch, 316 


Bubble sort, 285-288, 318 
bubble__sort, 288 
buffer_screen_region, 396-398 
buffer__video__region, 418 
buffered_input, 150 


C 


C.DAT, 242-243 

cale, 427-430 

ealloc, 350, 351 

Case 

-sensitive comparisons, 44-47, 71-76 

manipulation, 26-28 

change_directory, 169 

change__key, 223 

char *__strerror (const char #string);, 
637-638 

char *asctime (struct tm #time);, 440 

char *cgets (char *string);, 456 

char *ctime (long *seconds__since__ 
01__01__1970);, 470 

char *ecvt (double value, int number— 
of_digits, int *decimal__loc, int 
*sign);, 477-478 

char *far getdta (void);, 516-517 

char *fevt (double value, int number— 
of__digits, int *decimal__loc, int 
*sion);, 486 

char +fgets (char «string, int num— 
bytes, FILE «stream);, 490-491 

char *gcevt (double value, int num_ 
digits, char «str);, 508 

char *getcwd (char *directory, int 
num_bytes);, 514 | 

char *getenv(char *environment_— 
variable);, 517 

char *getpass (char *prompt);, 525 

char *itoa (int value, char *str, int 
radix);, 554 | 

char *ltoa (long value, char *str, int 
radix);, 566-567 

char *mktemp (char *template);, 575 

char *parsfnm (char *command__line, 
struct feb *filecontrol__block, int 
al__register);, 584 

char *ptr;, 381 

char «sbrk (int increment);, 607 

char *searchpath (char +filename);, 
608-609 


char *stpepy (char *destination, char 
#source);, 633 
char *streat (char «destination, char 
*source);, 634 | 
char *strepy (char *destination, char 
*gource);, 636 
char *strdup (char *str);, 637 
char *strerror (char *string);, 638 
char «strlwr (char *string);, 639-640 
char *strneat (char *destination, char 
*source, int num__bytes);, 640 
char *strnepy (char *destination, char 
*source, num__bytes);, 641-642 
char *strnset (char *string, char 
character, int max__bytes);, 643 
char *strpbrk (char *s1, char *s2);, 
643-644 
char «strrehr (char «str, char charac- 
ter);, 644 
char #strrev (char «string);, 645 
char «strset (char «string, char char- 
acter);, 645 
char «strstr (char *sl, char +*s2);, 646 
char *strtok (char *s1, char *s2);, 647 
char *strupr (char #string);, 649 
char *ultoa (unsigned long value, char 
*str, Int radix);, 658 
char far *grapherrormsg (int error_— 
code);, 534 
char__count, 36-37, 66-67 
char __index, 38, 65-66 
Character string 
centered on row, output routine for, 
324-325 
displayed using recursion, 97-99 
Character strings 
arrays of, 305-318 
*,* as, 2277-228 
Characters 
copying, 16-17 
displayed using ASCII code, 85, 87 
first occurrence of, in strings, 65- 
66, 67 
manipulation, 36-41 
null (\O), in a string, 13-14 
number of, in string, 64-65, 66-67 
See also Arrays 
check__character__available, 151 
clear__col, 216 


INDEX 675 


clear__display__page, 391-393 
clear__line, 393-394 
clear__screen, 215-216 
close__file, 172 
Command lines 
parameters displayed using recur- 
sion, 113 
processing, 80-82 
user-friendly, 319-320 
compare__strings, 307 
CONFIG.SYS, 209 
Conversion routines, 76-78 
copy_string, 19, 20-21, 69-70 
Copying 
fast, recursion used for, 107-109 
fast, of string, 59 
strings, 69-70 
COUNT 
to display number of file lines, 
121-122 
to display number of redirected 
lines, 120-121 
create__file, 170 
create__unique_file, 188-189 
ctr]__break__status, 163-164 
Cursor, manipulation of, 210-215 
cursor__back, 212-2138 
cursor__down, 211 
cursor__forward, 212 
cursor__home, 213 
cursor__up, 210-211 


D 


define__function__key, 223-224 
delete__file, 175-176 
DIR, 227 
stdout redirected for, 119-120 
DIR command, 115-116 
output to DIR.LST, 116-117 
with PRN, 117 
DIR.LST file, from DIR output, 
116-117 
direct_IO, 147 
disk__information, 155 
Display attributes 
changing, 337 
naming, 338 
values of, 322, 323 
DISPLAY.C, 232-233 
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Display page. See Video display pages 
display__trame, 409-411 . 
display__memo, 411-414 
display__menu, 408 
display__popup—_menu, 418, 420-422 
display_string, 97-99 | 
div__t div (int numerator, int denom- 
inator);, 473-474 
DOS 
directory, 226-228 
environment, accessing, 82-84 
memory map. See Memory map 
standard input source. See stdin 
standard output destination. See 
~ stdout 
dos.h, 139-140, 192 
with BIOS services, 192 
DOS system services, 140-190 
INT 21H with, 138-139 
interface with, 135-136 
use of 8088 registers in, 136-138 
DOS__version, 161-162 
double acos (double);, 438 
double asin (double);, 440-441 
double atan2 (double, double);, 442 
double atan (double);, 441-442 
double atof (char *str);, 443 
double cabs (struct complex number), 
454 
double ceil (double);, 455 
double cos (double);, 464 
double cosh (double);, 464-465 


double difftime (time_—_t time2, time__t 


timel);, 472-473 
double exp (double value);, 481-482 
double fabs (double value);, 482 
double floor (double value);, 495 
double fmod (double x, double y);, 
495-496 
double frexp (double value, int *expo- 
nent);, 504 
double hypot (double x, double y);, 539 
double ldexp (double value, int expo- 
nent);, 556 
double log10 (double value);, 562 
double log (double value);, 561-562 
double matherr (struct exception 
*except);, 567-568 


double modf (double value, double 


+integer_portion);, 575 
double poly (double x, int degree, 
double *poly_array);, 588 
double pow10 (int power);, 589 
double pow (double value, double 
power);, 588-589 
double sin (double value);, 626-627 
double sinh (double value);, 627 
double sqrt (double value);, 630 
double strtod (char «string, char 
#xend);, 646-647 
double tan (double value);, 650-651 
double tanh (double value);, 651 
double__sum__values, 2538 
Dynamic lists, 347-354 
doubly linked, 363-366 
maintaining sorted, 355-363 
Dynamic memory, 345-3880 


E 


8088 registers, 136-138, 139-140, 192 
end__list, 303 
env, 83, 305 
equal__strings, 44-45, 71-72, 306, 310 
Erasing, 215-216 
Error 
messages, 132-1383 
run-time, preventing, 7 
standard, 132-133 
EXTRACT.C, 242-244 


F 


Factorials, 100, 102-103 

fast_append, 21-22, 70-71 

fast__copy, 19-20, 69, 107-109 

fast__exchange, 31-32 

fast_insert, 23-24 

fast_pad, 38-34 | 

fibonacci, 104, 105 

Fibonacci number, 104, 105 

FILE #fdopen (int handle, char 
*open__type);, 487 


FILE *fopen (char *filename, char 


*access__type);, 497-498 
FILE *freopen (char +filename, char 
*access__type, FILE *stream);, 503 
file__pointer, 111-112 | 


file__reverse, 109-111 
FILECOPY, 233-234 
FILECOPY.C, 233-234 
Files 
deleting lines from, 242, 244-246 
displayed in reverse order using 
recursion, 109-111 
displaying directory for, 226-228 
displaying first lines of, 237-239 
displaying last lines of, 236-237 
displaying specified string in, 239 
enhancing capabilities of TYPE 
command for, 232-233 
last lines displayed using recursion, 
111-112 
locating, 84 
manipulation routines of, 225-246 
maximizing command-line flexibil- 
ity for, 234-236 
preceding lines of, 241-242 
removing portions of, 242-244 
replacing word with other word, 
239-241 
setting date and time stamp for, 
230-232 
setting or displaying attributes of, 
228-230 
utility programs for, 234-246 
fill-string, 40-41 
find__first, 180-182, 226-228, 
231-232 
find__next, 182-184, 226-228, 
231-232 
FINDSTR.C, 239 
FINDWORD, 127-128 
FIRST, 124-125 
FIRST-C, 237-239 
first__copy, 16-17 
first__difference, 45-46, 73-74 — 
first__nonwhite, 41-42 
float__bubble__sort, 312 
float_compare, 309, 311 
float_sum_—values, 253 
Floating-point value 
from user, input routine for, 
333-336 
on screen, output routine for, 
326-327 
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free, 352 
free__list, 360 
Function, assigning parameter value 
to, 60 
Functions 
pointers and, 59-62 
presentation of, 6 
prototypes, 6-8 


G 


generic__search, 309-310, 311 

get__cursor__position, 196 

get__date, 157 

get_directory, 179-180 

get__disk__transfer__address, 164-165 

get_disk__verification, 184-185 

get__file__attributes, 177-178 

get__file__datetime, 186-187 

get__float, 333-336 

get_free__disk_space, 166-167 

get_int, 332-333 

get__interrupt__vector, 165-166 

get_menu__response, 414-416 

get__popup__menu__response, 422-425 

get__program__segment__prefix, 
189-190 

get__prompted__float, 341-343 

get__prompted__int, 340-341 

get__prompted__string, 338-340 

get__shift_state, 204-205 

get__string, to provide default string, 
329-332 

get_time, 159 

get__video__mode, 203 

gettextinfo (struct text_info *text__ 
record);, 528 

getviewsettings (struct viewporttype 
far *view__port);, 530 


I 


I/O, user-consistent 
prompting floating-point value, 
341-3438 . 
prompting integer, 340-341 
prompting string, 338-340 
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I/O, user-consistent, continued 
providing, 336-338 
routines, 320-321, 336-334 
I/O redirection, 115-133 
counting lines of, 120-122 
displaying first lines of redirected 
input, 124-125 
displaying last lines of redirected 
input, 125-126 
displaying number of file elements, 
128-124 
displaying words of redirected 
input, 127-128 
filing intermediate results, 131-132 
placing line number before lines, 
122-123 
replacing word with other word, 
128-1380 
specifying number of spaces to 
right, 126-127 
stdin redirected for MORE com- 
mand, 118, 119 _ 
stdin and stdout defined, 115-116 
stdin and stdout redefined, 116-117 
using, 120-132 
I/O routines, 23, 319-344 
determining when to perform, 
386-387 
for video display pages, 391-403 
memory mapping and, 403 
user -consistent, 320-321, 336-334 
Index | 
incrementing, 48-49 
of characters, 73-74 
of substrings, 74-75 
inportb, 387 
Input routines, 329-336 
getting floating-point value from 
user, 333-336 
getting integer value from any 
location, 332-333 
providing default string, 329-332 


Input/Output. See I/O 
insert_string, 23 
int&6, 192 


INT 21H, 138-139 

INT, 192 

int abs (int);, 486. 

int absread (int disk, int num_ 
sectors, int first__sector, void 
«buffer);, 436 

int abswrite (int disk, int num_ 
sectors, int first__sector, void 
*buffer);, 437 

int access (char *filename, int access_ 
mode;, 4388 

int alloemem (unsigned paragraphs, 
unsigned *segment_address);, 439 

int atexit (atexit_t function__name),, 
442-448 : 

int atoi (char «str);, 443-444 

int bdos (int DOSfunction, unsigned 
dx, unsigned al);, 446-447 

int bdosptr (int DOSfunction, void 
*parameter, unsigned al);, 447 

int bioscom (int command, char byte, — 
int port—id);, 447-448 

int biosdisk (int command, int disk, 
int side, int track, int sector, int 
numsectors, void *buffer);, 448-449 


_ int biosequip (void);, 449-450 
int bioskey (int command);, 450-451 


int biosmemory (void);, 451 

int biosprint (ine command, int byte, 
int port__id);, 451-452 

int brk (void *end__datasegment);, 453 

int chdir (char *pathname);, 456-457 

int chmod (char «filename, int access);, 
457-458 | 

int chsize (int file_handle, long new__ 
s1ze);, 458 

int close (int file_handle);, 461-462 

int cprintf (char *format_string [, 
parameter|[, . . .]]);, 465-466 

int creat (char *filename, int access);, 
467-468 

int creatnew (char «filename, int 
attribute);, 468 

int creattemp (char *filename, int 
attribute);, 468-469 


int escanf (char *format__sequence [, 
arguments] );, 469 

int dosexterr (struct DOSERR 
*error_—info);, 474-475 

int dup2 (int old__file__handle, int 
new _file__handle);, 477 

int dup (int file__handle);, 476 

int eof (int file__handle);, 479 

int exec...(char *path, char *arg0, 
char *argl..., NULL);, 480 

int far getbkcolor (void);, 510 

int far geteolor (void);, 513 

int far getgraphmode ();, 521 

int far getmaxcolor (void);, 522-523 

int far getmaxx (void);, 523 

int far getmaxy (void);, 523 


int far getpixel (int x__loc, int y__loc);, 


525 

int far getx (void);, 532 

int far gety (void);, 532 

int far graphresult (void);, 585-586 

int far textheight (char far *string);, 
653-654 

int far textwidth (char far *string);, 
654-655 | 

int felose (FILE *stream);, 485 

int feloseall (void);, 485-486 

int feof (FILE *stream);, 487 

int ferror (FILE *stream);, 488 

int fflush (FILE *stream);, 488 

int fgetc (FILE *stream);, 488-489 

int fgetchar (void);, 489 

int fgetpos (FILE +file_stream, 
fpos__t *file__position);, 489-490 

int fileno (FILE *stream);, 491-492 

int findfirst (char *path, struct ffblk 
*fileblock, int attribute);, 492-493 

int findnext (struct ffblk *fileblock);, 
493-494 

int flushall (void);, 495 

int fprintf (FILE *stream, char 
*format__sequence [, argu- 

ments...]);, 499 

int fpute (int character, FILE 
*stream);, 500 
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int fputs (char «str, FILE *stream));, 
501 

int fread (void «pointer, int num_ 
bytes, int num__items, FILE 

*stream);, 501-502 

int freemem (unsigned segment);, 
502-5038 

int fscanf (FILE «stream, char 
format__sequence [, argument... ]);, 
504-505 

int fseek (FILE *stream, long offset, 
int location);, 505 

int fsetpos (FILE «file__stream, const 
fpos__t *file__position);, 505-506 

int fstat (char *handle, struct stat 
*stat__info);, 506 

int fwrite (void «buffer, int num_ 
bytes, int num__items, FILE 
*stream);, 507-508 

int getebrk (void);, 511 

int getc(FILE *stream);, 511 

int getchar(void);, 512 

int getche(void);, 512-513 

int getch(void);, 511-512 

int getcurdir (int drive, char *direc- 
tory);, 518-514 


‘int getdisk (void);, 516 


int getftime (int file__handle, struct 
ftime *file_stamp);, 520-521 

int gettext (int left__corner, int top_— 
corner, int right__corner, int 
bottom__corner, void *buffer);, 527 

int getverify (void);, 531 

int getw (FILE *stream);, 531 

int gsignal (int signal);, 536 

int inport (int port_number);, 541 

int inportb (int port_number);, 542 

int int86 (int interrupt—_number 
union REGS *inregs, union REGS 

*outreg’s);, 543 

union REGS *inregs, union REGS 
*segregs);, 544 

int intdos(union REGS *inregs, union 
REGS *outregs);, 545 

int intdosx(union REGS #inregs, union 
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int intdosx, continued 
REGS xoutregs, struct SREGS 
*outregs, struct SREGS 
sregs);, 545-546 
int ioctl (int devhandle, int command 
[, int argdx, int argex]);, 547 
int isalnum(int character);, 548 
int isalpha (int character); 548 
int isascii(int character);, 549 
int isatty (int devicehandle); 549 
int isentrl(int character);, 550 
int isdigit(int character);, 550 
int isgraph(int character);, 551 
int isprint(int character);, 552 
int ispunct(int character):. 552int 
isspace(int character);, 553 
int isxdigit(int character);, 5538-554 
int kbhit (void);, 554-555 
int lock (int filehandle, long offset, 
long length);, 561 
int mkdir (char *DOSpathname);, 573 
int movetext (int left__corner, int top_ 
corner, int right__corner, int 
bottom_—corner, int new__leftcorner, 
int new__topcorner);, 577-578 
int open (char *DOSpathname, int 
access__type[, int permissions]);, 
581-582 
int peek (int segment, int offset);, 585 
int peekb (int segment, int offset);, 585 
int printf (char «format_sequence [, 
argument...]);, 589-590 
int pute (int character, FILE 
_ *gtream);, 591 
int putch (int character);, 591 
int putchar(int character);, 592 
int putenv (char *environment— 
entry);, 592-593 
int puts (char *string);, 594-595 
int puttext (int left_corner, int top_— 
corner, int right__corner, int 
bottom_corner, void *buffer);, 595 
int putw (int word, FILE *stream);, 
595-596 
int randbrd (struct feb *file__control— 
block, int num__records);, 597-598 
int randbwr (struct feb *file__ 
control__block, int num_records);, 
598-599 


int random (int boundary);, 599 

int rand(void);, 597 

int read (int file__handle, void «buffer, 
int num__bytes);, 601 

int registerbgidriver (void 
(«driver)(void));, 603 

int registerbgifont (void(*font)(void));, 
603-604 

int rename (char *oldname, char 
¢newname);, 604 

int rewind (FILE #stream);, 605 

int rmdir (char «directory__name);, 
605-606 

int scanf (char format_sequence [, 
argument...]);, 607-608 

int setblock (int segment, int 
newsize__in__bytes);, 611 

int setcbrk (int status);, 612 

int setdisk (int disk__drive);, 614 

int setftime (int file__handle, struct 
ftime +file_stamp);, 616 | 

int setymp (jmp__buf task__state);, 
617-618 

int setmode (int filehandle, unsigned 
mode);, 619-620 

int spawn...(int mode, char 
*command, char «arg [,...], 
NULL);, 628-629 

int sprintf (char «string, char 
#format__sequence[, argument...] );, 
629-630 

int sscanf (char *string, char 
format__sequence [, argument...] );, 
631 

int stat (char «pathname, struct stat 
*stat__info);, 631-632 

int stime (long *seconds);, 633 

int stremp (char *s1, char +*82);, 635 

int strespn (char *sl, char *s2);, 
636-637 

int stricmp (char *s1, char *s2);, 
638-639 

int strnemp (char *sl, char *s2, int 
num__bytes);, 641 

int strnicmp (char «sl, char *s2, int 
num __bytes);, 642 

int system (char *~DOScommand);, 650 

int toascii (int character);, 655-656 

int tolower (int character);, 656-657 


int toupper (int character);, 657 
int ungete (char character, FILE 
*stream);, 658-659 
int ungetch (char character);, 659 
int unlink (char *DOSfilename);, 660 
int unlock (int filehandle, long offset, 
long num__bytes);, 661 
int vfprintf (FILE *stream, char 
format__sequence, va__list arglist);, 
663 
int vfscanf (FILE *stream, char 
format__sequence, va__list arglist);, 
663-664 
int vprintf (char format_sequence, 
va_list arglist);, 664 
int vseanf (char format__sequence, 
va_list arglist);, 665 
int vsprintf (char *string, char 
format_sequence, va__list arglist);, 
665-666 
int vsseanf (char «string, char 
format__sequence, va__list arglist);, 
666 
int wherex (void);, 666-667 
int wherey (void);, 667 
int write (filehandle, void *buffer, int 
num__bytes);, 669 
int__.chmod (char +*filename, int 
function[, int attribute]);, 457 
int__close (int file__handle);, 461 
int__creat (char +*filename, int 
attribute);, 466-467 
int__read (int file__handle, void 
«buffer, int num__bytes);, 600-601 
int__tolower (int character);, 656 
int__toupper (int character);, 657 
int__write (filehandle, void *buffer, 
int num__bytes);, 668-669 
int__bubble_sort, 312 
int__open (char *DOSpathname, 
int access__type);, 580 
int__pointer, 57, 59 
int_sum__values, 253 
int__to__ascil, 77-78 
intdos, 139-140, 141, 142 
Integer value 
from any location, input routine 
for, 332-333 | 
in row and column, output routine 
for, 325-326 
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Integer values, significant bit for, 104, 
105-106 
integer__variable, 57 
Interface 
BIOS, 191-206 
DOS, 135-190 
Interrupts 
for BIOS services, 192 


K 


Keyboard reassignment, 222-224 
keyboard__service, 152 


L 


LAST, 125-126 
LAST.C, 236-237 
last__nonwhite, 42-43 
ldiv__t Idiv (long numerator, long 
denominator);, 556-557 
Least squares fit, 265-269 
computing residual value in, 
268-269 
estimating missing points in, 267 
returning line of best fit in, 
266-267 
least__square, 266-267, 268 
LINENUM 
redirecting output from, 122-123 
to place line number before lines, 
122-123 
list__delete, 362-363 
list__insert, 355-358 
list__separator, 300-302 
Lists, dynamic, 347-354 
doubly linked, 363-366 
maintaining sorted, 355-363 
long atol (char *str);, 444 
long biostime (int command, long 
new__realtime);, 452 
long dostounix (struct date «date__ptr, 
struct time *time_—ptr);, 475 
long farcoreleft (void);, 483 
long filelength (int file_handle);, 491 
long ftell (FILE *stream);, 507 
long labs (long value);, 555-556 
long lseek (int filehandle, long offset, 
int location);, 565-566 
long strtol (char «string, char **end, 
int radix);, 648 
long tell (int filehandle);, 651 
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long time (long *seconds);, 655 
Lowercase 
manipulation, 26-28 
See also Case 
strings in, 68 
LS, 226-228 
LS.C, 226-228 
Isearch, 316 
lseek, 176-177 


M 


Macros 
for segmental searching, 276 
using, 269-270 
main, 112-113 
make—directory, 167-168 
malloc, 350, 351 
maxchar, qualifier, 69 
maximum__value, 256 
median__value, 256-258 
Memory , 
allocating, in linked lists, 350, 351 
dynamic, 345-380 
freeing, allocated by lst, 360 
mapping, 85, 87, 381-4038 
model, 140-141 
releasing, in linked lists, 352 
Memory addresses, 56-59 
ampersand (&) operator and, 56-57, 
61-62 
incrementing, 64 
locations of offset, 382-383 
locations segment, 382 
pointers and strings and, 62-64 
memory__map__get, 399-400 
memory size, 204 
Menus 
applications for, 405-407 
displaying, 411-414 
framing, 408-411 
pop-up, 417-425 
pop-up, advanced video, 425-430 
pop-up, math with, 425-430 
structure of, 407-408 
user selection of, 414-416 
mid__index, 277-283 
minimum__value, 255 
modal__value, 259-261 
MORE 
stdin redirected for, 118, 119 


to display screenful of information, 
180-131 
MORE.C, 180, 234-236 


N 


next__str__occurrence, 52-53 
no__echo__read, 148 
Nodes, 348-354 
in binary trees, 367-368, 371-3738, 
375-378 
in linked lists, 358-359, 360-363 


O 


open__file, 171 
Output routines, 321-328 
on display pages, 322 
to define display attributes, 322, 
323 
to output character string centered 
on row, 324-325 
to output integer value in row and 
column, 325-326 
to output prompt text to screen, 
327-328 | 
to place floating-point value on 
screen, 326-327 
to specify row and column location, 
322, 323-324 


P 


pad_string, 38, 35-36 
page__location, 391 
Parameters | 
call by value for, 60 
command-line displayed using 
recursion, 113 
for command-line access, 80-82 
presentation of, 6 
stored in stack, 114 
pattern-index, 53-54 
Patterns, matching, 53-54 
Pipe redirection, 118-119 
Pointers 
arrays of, 79-80 
defined, 56, 381 
far, 84-87 
functions and, 59-62 
in doubly linked lists, 3638-365 
in dynamic lists, 349-354 
manipulation of, 55-87 


Pointers, continued 
near, 84, 382 
self-referential structure and, 349 
strings and, 62-64 
Portability, 104 
print__blinking, 220 
print__bold, 221 
print__reverse__video, 219-220 
print__sereen, 193 
printf, 122-123 
Printing, 117-118 
PRN, 117 
Programs 
developing user-consistent, 
320-321, 336-334 
utility, 234-246 
put__centered__string, 324-325 
put__float, 326-327 
put_int, 325-326 
put_line, 402-403 
put__prompt, 327-328 
put_string, 322, 323-324, 327, 337 


Q 

qsort, 316 

Question mark (?), 53 
Quick sort, 304-305, 318 
quick__sort, 304-305 
Quotation marks (“ ”), 18 


R 


read__file, 173-174 
read__pixel, 202 
Recursion, 89-114 
defined, 89, 94 
factorial, 100, 102-103 
stack and, 114 
used to display character string, 
97-99 
used to display files in reverse 
order, 109-111 
used to display last line of file, 
111-112 
used to display strings in reverse 
order, 99-100, 101 
used to fast copy, 107-109 
used to invoke main program, 
112-113 


used to terminate strings, 94, 95-97 


with digit value, 90-94, 95 
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REMOVE.C, 242, 244-246 
remove__character, 37-38 
remove__directory, 168-169 
remove__substring, 51-52 
rename__file, 185-186 
REPLACE, 128-1380 
REPLACE.C, 239-241 
replace__char__index, 39-40 
replace__character, 67 
restore__cursor, 214-215 
restore__screen__region, 400-402 
restore__video__region, 418 
return__type, 252-253 
reverse__string, 28-29 
right__char__index, 38-39 
ROM BIOS. See BIOS services 
Run-time errors, preventing, with 
function prototypes, 7 
Run-time library, 2-3, 485-668 
allocating memory using, 350, 351 
ANSI routines and, 224 
BIOS services in, 192 
DOS system services routines in, 
141 
releasing memory using, 352 
returning byte value from port 
using, 387-388 
searching and sorting routines for, 
316 


S 


save__cursor, 214 
Screen. See Video screen 
seroll__down, 198-199 
scroll__up, 197-198 
Searching 
algorithms, 273-274 
arrays, 274-275 
binary, 276-285 
developing generic routines for, 
316-318 
run-time library routines for, 316 
sequential, 275-276 
sequentially, 316-318 
second__copy, 17 
Selection sort, 288-292 
selection__sort, 292 
Sequential search, 275-276, 316-318 
sequential__search, 275-276 
SET command, 82-84 


684 TURBO C PROGRAMMER’S LIBRARY 


set__active__display__page, 197 
— get__blink, 217-218 
set__bold, 217 
set__border__color, 205-206 
set__color__palette, 200-201 
set__colors, 219 
set__cursor, 210 
set__cursor__positions, 194-195 
set__cursor__size, 195 
set__date, 158 
set__disk__transfer__address, 154 
set__display__page__attribute, 
394-395 
set__drive, 153 
set__file__attributes, 178-179 
set__file__datetime, 187-188 
set_interrupt__vector, 156 
set__line__attribute, 395-396 
set_reverse, 218 
set__time, 160-161 
set__video__mode, 193-194 
setfillpattern (char far «fill__pattern, 
int color);, 615 
Shell sort, 293-297 
shell__sort, 296-297 
show —_digit, 90-94, 95 
show _first, 62. 
show__reverse, 99-100, 101 
show __second, 63 
show__string, 63-64 | 
SHOWENV PATH= program, 83-84 
slashC, 127-128 
— slashvV, 127-128 
SORT, 119-120 
Sorting 
algorithms, 273-274, 284-285 
developing generic routines for, 
316-318 
run-time library routine for, 316 
with bubble sort, 285-288, 318 
with quick sort, 297-305, 318 
with selection sort, 288-292 
with Shell sort, 293-297 
Source code 
in run-time library, 2-3 
minimizing, 18-19 
presentation of, 5-6 
STAMP.C, 230-232 


Standard deviation | 
described, 261-263 
determining, of values in an array, 
264-265 
Standard input. See stdin 
Standard output. See stdout 
standard__deviation, 264-265 
STAT.C, 124 
STATS, 123-124 
stderr, 1382-133 
stdin 
defined, 115-116 
redefining, 116-118 
redirected for MORE command, 
118, 119 
redirected for printing, 117-118 
redirected for SORT, 119 
used with COUNT, 121-122 
used with LINENUM, 122-123 
stdin__char, 142-143 
stdout 
defined, 115-116 
redirected for DIR, 119 
redirected for printing, 117-118 


stdout__output, 143-144 


stdprn__output, 146 
stdout, redefining, 116-118 
str__binary__search, 308 
str__bubble_sort, 312 
str__count, 50-51, 75-76 
str__index, 48, 49-50 
str__quick_sort, 314-315 
str__selection__sort, 318 
str__sequential_search, 306 
str__shell_sort, 313-314 
str__to__lowercase, 27, 68 


str__to_uppercase, 27-28, 68 


strehr (char «string, char letter);, 
634-635 
string__compare, 46-47, 72-73 
string__display, 149 | 
string__exchange, 31, 32-33 
string__length, 64-65, 94, 95-97 
String(s) 
append routines, 21-23, 70-71 
characters, 12-14, 36-41 
converted from integer value, 77-78 
converted to integer value, 76-77 


Strings, continued 
copy routine, 19-21 
default, 329-332 
displayed in reverse order using 
recursion, 99-100, 101 
exchanging, 30-33 
first occurrence of character in, 
65-66, 67 
length of, 15 
manipulation of, 64-76 
number of characters in, 64-65 
number of occurrences of character 
in, 66-67 
padding, 33-36 
as parameters, 14 
pointers and, 62-64 
recursion used to terminate, 94, 
95-97 
reversal, 28-29 
routines, 11-54, 64-76 
routines, in run-time library, 2-3 
See also Substrings 
Strings(s), comparisons, 43-47 
Strings(s) insertion routines, 23-25 
struct country *country_—_info (int 
country __code, struct country 
*country—info);, 465 
struct tm *gmtime(long *clock);, 533 
struct tm +localtime (long *seconds);, 
560 
Substrings 
manipulation of, 47-53 
number of occurrences of, in a 
string, 75-76 
sum__values, 253-254 


T 


TAB, 126-127 

TAB.C, 241-242 

TEE, 131-132 

TEE.C, 133 
terminate__resident, 162-163 
TYPE, 232-233 


U 


unsigned _rotl (unsigned value, 
int num_shifts);, 606 
unsigned __rotr (unsigned value, 
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int num__shifts);, 606-607 
unsigned coreleft (void);, 463-464 
unsigned far imagesize (int 

left__corner, int top——corner, int 

right__corner, int bottom_—corner);, 

539-540 
unsigned far setgraphbufsize 

(unsigned buffer _size);, 616-617 
unsigned FP__OF F (void far 

#far_pointer);, 498 
unsigned FP_SEG(void far 

+far__pointer);, 500 
unsigned getpsp (void);, 526 
unsigned int __clear87 (void);, 459 
unsigned int _status87 (void);, 632 
unsigned interrupt (*getvect(int 

interrupt_number))();, 530 
unsigned long —lrotr (unsigned long 

long__value, int num_shifts);, 564 
unsigned long strtoul (const char «str, 

char **end__pointer, int radix);, 

648-649 
unsigned long__lrot] (unsigned long 

long__value, int num_shifts);, 

563-564 
unsigned strlen (char *string);, 639 
Uppercase 

linked list for, 350-354 
manipulation, 26-28 
strings in, 68 
See also Case 
usertype va__arg (va_list param, 

usertype);, 661-662 
Utility programs, for file 

manipulation, 234-246 


V 

Value of type int, number of bits in, 
104, 105-106 

Variables 
differentiating between, 56-58 
memory addresses of, 56, 58 
presentation of, 6 
See also Pointers 

variance, 263-264 

Variance 
described, 261-263 
determining, of values in an array, 

263-264 
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Video display 
ANSI commands and, 207-224 
erasing, 215-216 
sereen attributes of, 216-222 
support with BIOS services, 
193-206 | 
Video display memory 
output characters in, 382-383 
two-dimensional array of, 384-386 
Video display pages, 322 
clearing contents of, 391-398 
erasing contents of line from, 
3938-394 
memory mapping, 390-391 
reading byte from segment and 
offset location of, 399-400 
restoring previously buffered 
region of, 400-402 
saving contents of, 396-398 
setting attribute byte for 
characters on, 394-395 
setting attribute for specific row 
on, 395-396 
writing character string to, 
402-403 
Video screen 
attributes, 216-222 
clearing contents of, 208 
pop-up menus used with, 425-430 
preventing snow on, 386-389 
processing with video pop-up 
menus, 425-430 
void *bsearch (void *key, void *base, 
int number__of__elements, int 
width, int (scompare_—function)());, 
4538-454 
void *calloc (size_t 
number —_of__elements, 
size_t element__size);, 455 
void «lfind (void *key__desired, 
void *base__address, int 
*num__elements, int 
element__width, int 
(xcompare—function)());, 557-558 
void *lsearch (void *desired__key, void 
*«bpase__address, int num__elements, 
int width, int 
(xcompare_function)());, 564-565 
void «malloc (size_t num__bytes);, 567 
void *memcepy (void «destination, void 
*gource, unsigned char letter, 
unsigned num__bytes);, 570-571 


void *memchr (void «ptr, char letter, 
unsigned num__bytes);, 571 

void «memcpy (void «destination, void 
«source, unsigned num__bytes);, 569 

void *memmove (void *destination, 

void *source, unsigned num__bytes);, 
572-573 

void «memset (void *ptr, char letter, 
unsigned num__bytes);, 573 

void #realloc (void *pointer, unsigned 
newsize__in__bytes);, 601-602 

void __exit (int status);, 480-481 

void _fpreset (void);, 498-499 

void abort (void);, 486 

void assert (int condition);, 441 

void clearerr (FILE *file_pointer);, 
460 

void clreol (void);, 462-463 

void elrser();, 463 

void eputs (char *string);, 466 

void ctrlbrk (int (*function)(void));, 
470-471 

void delay (unsigned milliseconds);, 
A771 

void delline (void);, 471-472 

void disable (void);, 473 

void enable (void);, 479 

void exit (int status);, 481 

void far *far _graphgetmem 
(unsigned size);, 535 | 

void far *farcalloc (unsigned long 
number _of__entries, unsigned long 
entry —_size);, 482-483 

void far *farmalloc (unsigned long 
number —of__bytes);, 484 

void far *farrealloc (void far «ptr, 7 
unsigned long num__bytes);, 484- 485 

void far *MK__F'P (unsigned segment, 
unsigned offset);, 574 

void far _.graphfreemem (void far 
*pointer, unsigned bytes);, 534 

void far are (int xloc, int yloc, int 
start_angle, int end__angle, int 
radius);, 439-440 

void far bar3d (int left_corner, int 
top__corner, int right__corner, int 
bottom__corner, int depth, int 
top__flag);, 445-446 | 

void far bar (int left__corner, int 
top__corner, int right__corner, int 
bottom—corner);, 445 

void far circle (int xloc, int yloc, 


int radius);, 459 

void far cleardevice (void);, 460 

void far clearviewport (void);, 461 

void far closegraph (void);, 462 

void far detectgraph (int far 
*graph__driver, int far 
*oraph__mode);, 472 

void far drawpoly (int 
number _—_of__points, int far 
*points);, 475-476 

void far ellipse (int x__loc, int y__loc, 
int start_angle, int end_angle, int 
X__radius, int y__radius);, 478-479 

void far fillpoly (int 
number __of__points, int far 
*points);, 492 

void far floodfill (int x__loc, int y__loe, 
int border _—_color);, 494-495 

void far getarccoords (struct 
arccoordstype far *arc__coord);, 509 

void far getaspectratio (int far 
*x__aspect, int far *y__aspect);, 510 

void far getfillpattern (char far 
*fill__pattern);, 519 

void far getfillsettings (struct 
fillsettingstype far *fill__info);, 
519-520 | 

void far getimage (int left__corner, int 
top__corner, int right__corner, int 
bottom_—corner, void far *image); 
521-522 

void far getmoderange (int graph 
driver, int far *lowest__mode, int far 
«highest__mode);, 523-524 

void far getpalette (struct palettetype 
far *palette);, 524 

void far gettextsettings (struct 
textsettingstype far text__record);, 
528-529 

void far initgraph (int far 
*graph__driver, int far 
*graph__mode, char far 
*driver__path);, 540-541 

void far line (int xstart, int ystart, int 
xend, int yend);, 558 

void far linerel (int x__offset, int 
y—oftiset);, 559-560 

void far lineto (int x__loc, int y__loc);, 
559 

void far moverel (int x__offset, int 
y—offset);, 576-577 
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void far moveto (int x—_loc, int 
y—loc);, 578 

void far outtext (char far *string);, 583 

void far outtextxy (int x__loc, int 
y__loc, char far «string);, 583 

void far pieslice (int x__loc, y__loe, int 
start_angle, int end__angle, int 
radius);, 586-587 

void far putimage (int x__loc, y__loc, 
void far «buffer, int operation);, 593 

void far putpixel (int x__loc, int 
y__loe, int pixel__color);, 594 

void far rectangle (int left__corner, int 
top__corner, int right__corner, int 
bottom_corner);, 602-603 

void far restorecrtmode (void), 
604-605 

void far setactivepage (int 
page__number);, 609-610 

void far setallpalette (struct 
palettetype far «palette);, 610 

void far setbkcolor (int 
background_color);, 610-611 

void far setcolor (int color);, 613 

void far setfillstyle (int fill__style, 
int color);, 615-616 

void far setgraphmode (int 
graphics__mode);, 617 

void far setlinestyle (int line__style, 
unsigned pattern, int thickness), 
618-619 

void far setpalette (int index, int 
eolor);, 620 

void far settextjustify (int horizontal, 
int vertical);, 620-621 

void far settextstyle (int font, int 
direction, int size);, 621-622 

void far setusercharsize (int xmult, int 
xdiv, int ymult, int ydiv);, 623 

void far setviewport (int left__corner, 
int top__corner, int right—_corner, 
int bottom_corner, int clip);, 
625-626 
void far setvisualpage (int 

page__number);, 626 

void farfree (void far *ptr);, 483-484 

void fnmerge (char *path, char «drive, 
char «directory, char «filename, 
char *extension);, 496-497 

void fnsplit (char *path, char *drive, 
char *directory, char *filename, 
char *extension);, 497 
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void free (void *pointer);, 502 

void geninterrupt (int 
interrupt_number); 508-509 

void getdate (struct date 
*current_—_date);, 515 

void getdfree (int drive, struct dfree 
*disk__info);, 515-516 

void getfat (int drive, struct fatinfo 
*fat_info);, 517-518 

void getfatd (struct fatinfo *fat_info);, 
518 

void gettime (struct time 
*system_—_time);, 529 

void gotoxy (int x__loc, int y__loc);, 
533 

void harderr (int (*function__ptr) ());, 
537 

void hardresume (int resume_code);, 
537-538 

void hardretn (int error__code);, 538 

void highvideo (void);, 588-539 

void insline (void);, 542 

void intr (int interrupt__number, 
struct REGPACK +«regs);, 546-547 

void keep (int status, int paragraphs), 
555 

void longjmp (jmp__buf task__state, 
int return_value);, 562-563 

void lowvideo (void);, 563 

void movedata (int source__segment, 
int source_offset, int 
target__segment, int target__offset, 
unsigned num__bytes);, 576 

void movmem (void *source, void 
target, unsigned num__bytes);, 
578-579 

void normvideo (void);, 579 

void nosound (void);, 579-580 

void outport (int port_—id, int word), 
582 

void outportb (int port_id, char byte);, 
582 

void perror (char *string);, 586 

void poke (int segment, int offset, int 
value);, 587 

void pokeb (int segment, int offset, int 
value);, 587-588 

void gsort (void *base__address, int 
num__elements, int width, int 
(*compare_function)());, 596-597 

void randomize (void);, 600 


void segread (struct REGS 
*segment__registers);, 609 

void setbuf (FILE «stream, char 
«buffer);, 611-612 

void setdate (struct date 
*current__date);, 613 

void setdta (char far | 
#disk__transfer__address);, 614 

void setmem (void «address, int 
num_bytes, char letter);, 619 

void settime (struct time 
*system__time);, 622 

void setvbuf (FILE *stream, char 
«buffer, int type, unsigned 
num __bytes);, 623-624 

void setvect (int interrupt__number, 
void interrupt (*service routine) ());, 
624-625 

void setverify (int state);, 625 

void sleep (unsigned seconds);, 627 

void sound (unsigned frequency);, 628 

void srand (unsigned seed);, 630-631 

void swab (char *sl, char ¥*s2, int 
num__bytes);, 649-650 

void textattr (int attribute);, 652 

void textbackground (int 
background__color);, 652-653 

void texteolor (int color);, 653 

void textmode (int desired__mode);, 
654 

void tzet (void);, 657-658 

void unixtodos (long unixtime, struct 
date *date__ptr, struct time 
+time_—ptr);, 659-660 

void va__end (va_list parameter);, 662 

void va_start (va_list parameter), 
662-663 

void window (int left__corner, int 
top__corner, int right__corner, int 
bottom__corner);, 667-668 


White space, 41-43 
Wildeard characters 
matching, 53-54 
use of, 226-246 
word__size, 107 
write__char__and__attr, 199-200, 
321- 322 
write__file, 174-175 
write__pixel, 201 


The manuscript for this book was prepared and submitted to 
Osborne/McGraw-Hill in electronic form. The acquisitions editor 
for this project was Cynthia Hudson, the technical reviewer was 

Charles P. Jazdzewski, and the project editor was Fran 
Haselsteiner. 


Cover art by Bay Graphics Design Associates. Color separation by 
Colour Image. Cover supplier, Phoenix Color Corp. Book printed 
and bound by R.R. Donnelley & Sons Company, Crawfordsville, 

Indiana. 


Py te 
= 7 
PP ies a 

tS « | rf . 4 7 
(Meo 3 : Ri 
bess kK me i 
: \e kL ~ yamaln 
f d =P | 
cf a 
‘i 7 maf uy — 
3 = ~ weer, ' 


‘ ’ Ga 
‘ 3 ein 
r ay 
; a 
= Fae ; 
| 
¥ 
~ b 


© 
7 
oo 
© 
= 
fn 


=? & 


un 
UY 


; 


TURBOC 


PROGRAMMER s 


Whether you’re just learning to use Borland’s Tu 


* 
ety 
aN 


you're developing professional programs, 
Programmer’s Library is a must for you. 


Kris Jamsa, author of the bestselling Turbo Das 
grammer’s Library, shows you how to develop 


library of hundreds of Turbo C® routines, ¢ nd ¢ 
tricks you need to master the Turbo © run-tir 
examining the code in this text you'll hg as 


In Turbo C* Programmer's Library, wea shee 


Meslisitematrilieeirieee 
meliiltci gs 
Recursion Be 32) 
The DOS and BIOS services” 
Array manipulation : 
Searching and sorting Me 
Dynamic list manipulation 
Memory mapped 1/0 
m Pop-up menu processing — 
The best way to develop good Pade. is 0 § 
and Turbo C* Programmer's Library pack: 
code and techniques than any other Turbo 
market. 


e Po ket r 
DOS: The Complete Reference, DOS: The Poc < 


DOS: Power User's Guide, Turbo Pascal® 4: The My: 
Reference, and The C Library. He holds aBS. de 
computer science from the United States A t 
and an M.S. degree in computer science fro m 


of Nevada at Las Vegas. He is currently a V AXNV MS. 


manager for the United States Air Force. 


0S/2 is a trademark of International Business Machines Corp. w 
registered trademarks of Borland international, inc. 


ISBN 0-0?-881354-84 


ben 
Of 


ia es ; os ihe ¢ i 
i iin 


: a 
rf 
' 
‘ 
, 
ae 
"PF 
’ 


scec-45 


